When sending any sensitive information over the Internet, such as bank statements, payroll data, insurance claims, medication details, or even your home address, it’s important to ensure that your data is protected on its journey from your sent box to the recipient’s inbox. This is where DataMotion’s secure message delivery API, with its end-to-end encryption, comes in handy.
The Secure Message Delivery API
DataMotion, Inc. is an API company specializing in secure data transfer. Our secure message delivery API uses end-to-end encryption, which allows you to send a secure message to anyone with a valid email address while protecting the contents of your messages in transit. In addition to securely sending messages, the API allows you to track and retract your messages as well.
In this guide, I will walk you through creating a DataMotion account and how to get started with our secure message delivery API.
What You Will Need
For this tutorial you will need the following:
- A DataMotion trial or production license
- A Postman account to test the API
How to Create a DataMotion API Account
The first step to utilize the DataMotion secure message delivery API is to create a DataMotion account. To do so, navigate to datamotion.com/portal, where you will see a list of plans displayed; select the ‘Secure Message Delivery’ bundle and click the ‘Try’ icon.
Once you have selected ‘Try’ you will see the secure message delivery API’s self-service center, where you will have the option to test DataMotion APIs, review documentation, and contact support if needed.
In the top right corner of the screen, there is a ‘Login’ button. Select this button to get started. A new pop up will display once the button is selected – at the bottom of this pop up, click ‘sign up here.’
After you have completed these steps, you will see a request for information and a section to create a password. Enter the required information and create your secure password.
Review and agree to the terms of service, then finish the process by selecting ‘Create Your Account.’ Your account has now been created, and you will automatically have a $25 balance to test our APIs.
Create an Application
Before moving on to testing the API in Postman, an API key and secret must be generated in order to authenticate each API request. The key and secret will be tied to an application for organizational purposes. You can generate multiple applications to organize your users and environments.
Once you have signed in, a new tab should appear titled ‘Applications.’ Within the ‘Applications’ tab, select the ‘Create Application’ button and give the application a name and description. Then select ‘Other’ for the application type and provide a description.
Select the ‘plus’ sign (+) in the center of the ‘API Keys’ section to the left of the ‘Application Details’ and copy the API secret that is provided in the pop up. Store this string somewhere safe, as we will need it later on and you will not be able to access it again through the DataMotion site.
Once you copy the secret, the pop up will close and in the ‘API Key’ section you will find your new API key. We will be using this key as well, so be sure to have it handy.
Download Postman Collection:
Now that your application is configured, and your API secret and key have been generated, it’s time to test our API. There are a few ways to test but for this tutorial we will utilize Postman, which is an application used for API testing.
Note: You can find Postman tips and tricks on DataMotion’s Twitter and LinkedIn pages as well as Postman demo videos on our site.
To start, navigate to the DataMotion ‘SecureMessage-Postman-Collection’ on GitHub to download the collection.
Once on GitHub, select the green ‘Code’ button to download the JSON file needed. There are a few ways to gather this information, but for this guide we will choose ‘Download Zip.’ Once downloaded, move the zip file to where you would like to store this collection and extract the files. You will see three JSON files once extracted.
From here, open Postman and create a new workspace by selecting the ‘Workspaces’ option at the top left of the screen followed by ‘+New Workspace.’
In the page that appears, name the collection ‘DataMotion Secure Message API’ and select ‘Create Workspace.’ You will now have an empty workspace in which to populate the secure message delivery API collection. Select ‘Import’ (located under the ‘Workspaces’ option) which you will see to the right of your workspace name.
Under the new file tab, select ‘Upload Files’ and navigate to the Secure Message Delivery API JSON file that was extracted from the GitHub zip file and select ‘Open.’ Once the file is opened, select ‘Import.’
You have successfully imported the DataMotion secure message delivery API collection!
Fill Out Request:
The only thing left to do is start testing the API. To do so, select the ‘Send a Secure Message’ request.
In the request URL textbox, you will see a variable for the Base URL. You can replace the variable shown as ‘{{BaseURL}}’ or populate it through the collection’s variable list so this will be represented in all three of the collection’s requests.
To populate the variable, select the ellipsis next to the collection name and select ‘Edit.’ In the Variables tab, next to the Base URL variable add ‘https://api.datamotion.com/SecureMessageDelivery/v1.2’ in the ‘Current Value’ section.
Once the Base URL variable is populated, return to the request. In the request URL textbox replace ‘{MessageDeliveryType}’ which comes after the Base URL, with ‘Email’.
You will see there is also a variable for the API key, {{UniqueID}} and secret, {{SecretValue}}. You can populate these variables with the key and secret we generated in the last section as we will use the same information for all three requestion in the collection.
If you navigate to the request’s ‘Header’ tab you will see the API key and secret variables. Since these variables are now populated, the headers are ready to go. Next, select the ‘Body’ tab.
In the ‘Body’ tab, you will be able to configure your secure message. The request body has already been outlined for you. If you do not see the outline make sure you have selected the ‘raw’ option above the request textbox.
You will want to update the JSON text to replace the dummy data provided. Below, I will walk through each section of the request and provide example entries, but keep in mind, you may need to customize these fields to properly test (especially the ‘To’ address!).
From
The ‘From’ address will be the address you are sending the secure message from. Enter in the address with which you created the API secret and key.
To
The ‘To’ address can be any address with a mailbox. To test, you can enter the same address you used for the from address or any address you have access to.
Cc (Optional)
Enter any additional email address that have a corresponding mailbox you would like copied.
Bcc (Optional)
Enter any additional email address that have a corresponding mailbox you would like to blind copy.
Subject (Optional)
Enter the subject of the email. For this test you will put ‘HR – New Hire Form’
Attachments (Optional)
To add an attachment, you will need to provide the base64 string, content type, FileName and ContentID. There are a few additional steps to gather this information automatically but for the demo today you can leave this section blank.
HtmlBody (Optional)
In this section you can add html text to send in the body of the message. For this example, you can keep this section blank.
TextBody (Optional)
Here outline the body in plain text and add the information you collected from the new hire form.
Once the request is fully configured, select ‘Send’ at the top left of the screen. In the response section, located directly below the request textbox, you should see a 200 HTTP status as well as your message ID and message expiration date.
To ensure the message went through, navigate to the inbox of the recipient address defined in the request. You should see a secure message waiting in your inbox.
Congratulations, you have sent your first secure message!
Conclusion
Now that you have created a DataMotion account and learned how to send a secure message you can be sure to protect the important messages you need to send. This functionality can be extended to your employees and customers, as our APIs make it extremely easy to seamlessly integrate secure messaging into your current apps and customer portals. By doing so, you will ensure important business messages and documents are delivered securely and compliance is consistently met.
Be sure to check out our Documentation and Getting Started page for additional help. For more information, contact our sales team.
