Common SecureMail Tasks

How do I...

Send messages?

Use the Send Message method of the Messaging API

Go there now

Read messages?

Use the Get Message method of the Messaging API

Go there now

Delete messages?

Use the Delete Message method of the Messaging API

Go there now

Retrieve folders?

Use the List Folder method of the Messaging API

Go there now

Create folders?

Use the Create Folder method of the Messaging API

Go there now

Delete folders?

Use the Delete Folder method of the Messaging API

Go there now


Have questions? Please contact us for further assistance.

Admin API

The Admin API uses session keys for authentication, which you can get from a commonly accessed DataMotion web method, GetSessionKey. This SessionKey can then be used in every DataMotion API that uses session keys; not just the Admin API.

Note: Some Admin API methods cannot be used on the DataMotion Direct platform.

Authentication

The following methods handle authentication to the DataMotion Administration API

box icon

GET A SESSION KEY

This method authenticates a user and returns a session key to be used in subsequent API requests.

URL

{BaseURL}/Remote/Account/GetSessionKey

HTTP Method

POST

Header Values

KeyValueDescription
X-User-IdKyleCThe user ID of the Company Administrator. This parameter can either be replaced with X-Email (for the user's email address) or X-Single-Signn-On-Id (for the user's unique SingleSignOnId).
X-IvYj4ij9BV+k484FGvte8PNwInitialization vector used for encryption
X-Company-Automation-IDsample-bb0e779dd-13ba-4915-b42h-57sdh5df2adceThe automation ID provided when company is enabled for Admin API usage
Content-Typeapplication/jsonContent type
X-HashO3JyP8sn3h738kjadf8hbjFOznMcAig==The hash of the encrypted payload

Request Body Parameters

NameDescriptionTypeRequired
IpAddressThe IP address of the API callerStringN
TimeStampThe UTC time and date the request is sent. The timestamp typically must be within plus or minus 5 seconds of the server's UTC time.DateTime StringN
IdentityAn Identity structure containing the following valuesObjectY

Encryption Steps

Your company will be issued an Encryption Key (also referred to as a Pre-Shared Key or PSK) upon initial onboarding. This Encryption Key should be kept confidential and access to this key should be regulated by your company. See Libraries & SDKs for encryption examples.



  • 1

    Set up AES Encryption

    Initialize AES encryption with a key length of 256. Using this encryption, generate an Initilization Vector (IV) and encode the IV into a Base64 string. This should be passed as the "X-Iv" header value in the request.
  • 2

    Serialize Payload

    Serialize the payload (unencrypted) as JSON into a byte array.
  • 3

    Get Hash of Payload

    Generate a byte array of your Encryption Key. Using that key, obtain a hash of your unencrypted payload using HMACSHA512. Encode this value into a Base64 string. This should be passed as the "X-Hash" header value in the request.
  • 4

    Encrypt Payload

    Using AES256, encrypt the byte array from step 2, using your Encryption Key (as a byte array) and your IV (step 1).

Request Body Formats

Unencrypted JSON


{
     "IpAddress": "12.12.12.120",
     "TimeStamp": "2008/05/01 18:32:06",
     "Identity": {
         "UID": 123456,
         "Email": "email@example.com",
         "UserId": "username",
         "SingleSignOnId": "user123"
     }
}

Encrypted JSON


{
    "xAtGEJ4M69lkjsbndf8abnKJHSGD0sa8u3evZUhREIDfQRxLbpP3Xc19DASBsydjhVesNLXru3aUgy6C8fkdasjhbS348JHL+DxTwa1C3"
}

Response Body Parameters

NameDescriptionType
SessionKeyUsed to access all Admin and Messaging API methodsString

Response Body Formats

JSON


{
    "8SAJ04JALSD023QHU4KJEJHFDSLJK"
}
box icon

GET AN ENCRYPTION KEY (PSK)

This method returns a user's encryption key, or Pre-Shared Key.

URL

{BaseURL}/Remote/Account/GetEncryptionKey

Note: If a user's encryption key does not already exist, a new one will be generated.

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

Note: As past of the Request Body, at least one of the four fields below are required.

NameDescriptionTypeRequired
UIDUnique user identifier generated by the DataMotion platform. Also referred to as UniqueIdIntegerN
EmailSecure address of the user on the DataMotion platformStringN
UserIdUser-defined shortened login username that can be used on the DataMotion web portalStringN
SingleSignOnIdUser-defined unique user identifier within a companyStringN

Request Body Formats

JSON


{
    "UID": 123456,
    "Email": "email@example.com",
    "UserId": "username",
    "SingleSignOnId": "user123"
}

Response Body Parameters

NameDescriptionType
EncryptionKeyThe Encryption Key associated with the administrator's companyString

Response Body Formats

JSON


{
    "LKJSAHDBFO8AUSBDKLFHA3WOUBDSAK"
}
box icon

CREATE A NEW ENCRYPTION KEY (PSK)

This method generates and returns a new company encryption key, which will invalidate any existing key.

URL

{BaseURL}/Remote/Account/NewEncryptionKey

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
UIDUnique user identifier generated by the DataMotion platform. Also referred to as UniqueIdIntegerN
EmailSecure address of the user on the DataMotion platformStringY
UserIdUser-defined shortened login username that can be used on the DataMotion web portalStringN
SingleSignOnIdUser-defined unique user identifier within a companyStringN

Request Body Formats

JSON


{
    "UID": 123456,
    "Email": "email@example.com",
    "UserId": "username",
    "SingleSignOnId": "user123"
}

Response Body Parameters

NameDescriptionType
EncryptionKeyThe Encryption Key associated with the administrator's companyString

Response Body Formats

JSON


{
    "LKJSAHDBFO8AUSBDKLFHA3WOUBDSAK"
}

Account

These methods are used to perform basic account administration tasks, like viewing users and their privileges.

box icon

LIST USER ACCOUNTS

This method lists all company user accounts and their account summaries.

URL

{BaseURL}/Remote/Account/List

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
UserTypeIdThis field specifies the unique ID of the User’s UserType. A list of UserTypeIds can be obtained by calling GetUserTypesIntegerN
PageNumberThe page number to returnIntegerY
CompanyIdThe unique identifier of the user's company on the DataMotion platform. This field will always default to the CompanyId of the Admin accessing the APIStringN
OrderByAny field from this response that you can sort your results with (ie: "UniqueId", "Aid", "CompanyId", "Created", etc)StringY
FilterList a specific user account based on their secure address (Note: The Filter parameter can be left blank to list all accounts)StringY

Request Body Formats

JSON


{
    "UserTypeId":12345,
    "PageNumber":1,
    "CompanyId":0,
    "OrderBy":"UniqueId",
    "Filter":""
}

Response Body Values

NameDescriptionType
AccountsA complex type with the following values per accountObject
CountA count of accounts in the listInteger
CurrentPageThe current page of the listInteger
TotalPagesThe total number of pages in the responseInteger
TotalUsersThe total number of users in the responseInteger
PageSizeThe total number of users returned per pageInteger

Response Body Formats

JSON


{
    "Accounts":[
        {
            "UniqueId":375,
            "Aid":375,
            "CompanyId":112,
            "Created":"2013-02-19T09:26:00",
            "LastNotice":null,
            "DiskSpaceUsed":"<1 Kb",
            "EmailId":375,
            "Email":"boo@flemco.com",
            "EmployeeId":"9876543210",
            "FirstName":"Breanna",
            "LastName":"Thrasher",
            "LastLogin":"2013-02-19T09:32:00",
            "MessagesReceived":0,
            "MessagesSent":0,
            "UserId":"boo",
            "UserTypeId":250,
            "Errors":{
                "Email": [
                    "This Email field is not a valid e-mail address.",
                    "The Email field is required."
                ],
                "UserTypeId": [
                    "The field UserTypeId must be between 1 and 2147483647."
                ]
            }
        },
        {
            "UniqueId":378,
            "Aid":378,
            "CompanyId":112,
            "Created":"2013-02-19T17:08:00",
            "LastNotice":null,
            "DiskSpaceUsed":"<1 Kb",
            "EmailId":378,
            "Email":"boo1@flemco.com",
            "EmployeeId":"9876543210",
            "FirstName":"Breanna",
            "LastName":"Thrasher",
            "LastLogin":null,
            "MessagesReceived":0,
            "MessagesSent":0,
            "UserId":"boo1",
            "UserTypeId":250,
            "Errors":{
                "Email": [
                    "This Email field is not a valid e-mail address.",
                    "The Email field is required."
                ],
                "UserTypeId": [
                    "The field UserTypeId must be between 1 and 2147483647."
                ]
            }
        }
    ],
    "Count":2,
    "CurrentPage":1,
    "TotalPages":1,
    "TotalUsers":2,
    "PageSize":50
}
box icon

CREATE A USER ACCOUNT

This method creates a company user account.

URL

{BaseURL}/Remote/Account/Create

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
EmailSecure address of the user on the DataMotion platformStringY
UserIdUser-defined shortened login username that can be used on the DataMotion web portalStringN
SingleSignOnIdUser-defined unique user identifier within a companyStringN
PasswordThe user's passwordStringN
FirstNameFirst name of the userStringN
LastNameLast name of the userStringN
PhonePhone number of the userStringN
CompanyIdThe unique identifier of the user's company on the DataMotion platform. This field will always default to the CompanyId of the Admin accessing the APIIntegerN
EmployeeIdA miscellaneous field (recommended to be used for Employee IDs)StringN
MiscellaneousA miscellaneous fieldStringN
DisabledThis field indicates whether the user account is currently disabled or notBooleanN
UserTypeIdThis field specifies the unique ID of the User’s UserType. A list of UserTypeIds can be obtained by calling GetUserTypesIntegerY
ReceiveOffersThis field indicates whether the User would like to receive offers and updates from DataMotion. The default is falseBooleanN

Request Body Formats

JSON


{
    "Email":"jane@example.com",
    "UserId":"janetheadmin",
    "SingleSignOnId":"ExampleJane",
    "Password":"|?|Y||p@$5|//0rd",
    "FirstName":"Jane",
    "LastName":"Doe",
    "Phone":"8675309",
    "CompanyId":112,
    "EmployeeId":"1564872",
    "Miscellaneous":"",
    "Disabled":false,
    "UserTypeId":252,
    "ReceiveOffers":false
}

Response Body Values

NameDescriptionType
UniqueIdUnique user identifier generated by the DataMotion platform. Also referred to as UIDInteger
EmailSecure address of the user on the DataMotion platformString
UserIdUser-defined shortened login username that can be used on the DataMotion web portalString
SingleSignOnIdUser-defined unique user identifier within a companyString
PasswordThe user's password. Note: the password field will always be returned blankString
FirstNameFirst name of the userString
LastNameLast name of the userString
PhonePhone number of the userString
CompanyIdThe unique identifier of the user's company on the DataMotion platform. This field will always default to the CompanyId of the Admin accessing the APIInteger
EmployeeIdA miscellaneous field (recommended to be used for Employee IDs)String
MiscellaneousA miscellaneous fieldString
DisabledThis field indicates whether the user account is currently disabled or notBoolean
UserTypeIdThis field specifies the unique ID of the User’s UserType. A list of UserTypeIds can be obtained by calling GetUserTypesInteger
ButtonUserThis field indicates whether the user uses the Outlook button pluginBoolean
ReceiveOffersThis field indicates whether the User would like to receive offers and updates from DataMotion. The default is falseBoolean
ErrorsValidation errors for submitted requestsDictionary<string,List<string>>

Response Body Formats

JSON


{
       "UniqueId":11597,
       "Email":"jane@example.com",
       "UserId":"janetheadmin",
       "SingleSignOnId":"ExampleJane",
       "Password":"",
       "FirstName":"Jane",
       "LastName":"Doe",
       "Phone":"8675309",
       "CompanyId":112,
       "EmployeeId":"1564872",
       "Miscellaneous":"",
       "Disabled":false,
       "UserTypeId":252,
       "ButtonUser":false,
       "ReceiveOffers":false
    "Errors":{
    "Email": [
        "This Email field is not a valid e-mail address.",
        "The Email field is required."
    ],
    "UserTypeId": [
        "The field UserTypeId must be between 1 and 2147483647."
    ]
}
box icon

VIEW A USER ACCOUNT

This method returns a user's account details.

URL

{BaseURL}/Remote/Account/Read

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
UIDUnique user identifier generated by the DataMotion platformIntegerY
EmailSecure address of the user on the DataMotion platformStringY
UserIdUser-defined shortened login username that can be used on the DataMotion web portalStringN
SingleSignOnIdUser-defined unique user identifier within a companyStringN

Request Body Formats

JSON


{
   "UID":11597,
   "Email":"jane@example.com",
   "UserId":"janetheadmin",
   "SingleSignOnId":"ExampleJane"
}

Response Body Values

NameDescriptionType
UniqueIdUnique user identifier generated by the DataMotion platform. Also referred to as UIDInteger
EmailSecure address of the user on the DataMotion platformString
UserIdUser-defined shortened login username that can be used on the DataMotion web portalString
SingleSignOnIdUser-defined unique user identifier within a companyString
PasswordThe user's password. Note: the password field will always be returned blankString
FirstNameFirst name of the userString
LastNameLast name of the userString
PhonePhone number of the userString
CompanyIdThe unique identifier of the user's company on the DataMotion platform. This field will always default to the CompanyId of the Admin accessing the APIInteger
EmployeeIdA miscellaneous field (recommended to be used for Employee IDs)String
MiscellaneousA miscellaneous fieldString
DisabledThis field indicates whether the user account is currently disabled or notBoolean
UserTypeIdThis field specifies the unique ID of the User’s UserType. A list of UserTypeIds can be obtained by calling GetUserTypesInteger
ButtonUserThis field indicates whether the user uses the Outlook button pluginBoolean
ReceiveOffersThis field indicates whether the User would like to receive offers and updates from DataMotion. The default is falseBoolean
ErrorsValidation errors for submitted requestsDictionary<string,List<string>>

Response Body Formats

JSON


{
    "UniqueId":371,
    "Email":"jfleming@flemco.com",
    "UserId":"jfleming",
    "SingleSignOnId":"",
    "Password":"",
    "FirstName":"John",
    "LastName":"Fleming",
    "Phone":"7654045852",
    "CompanyId":112,
    "EmployeeId":"",
    "Miscellaneous":"",
    "Disabled":false,
    "UserTypeId":252,
    "ButtonUser":false,
    "ReceiveOffers":false,
    "Errors": {
        "Email": [
            "This Email field is not a valid e-mail address.",
            "The Email field is required."
        ],
        "UserTypeId": [
            "The field UserTypeId must be between 1 and 2147483647."
        ]
    }
}
box icon

UPDATE A USER ACCOUNT

This method updates a company user account, overwriting all existing values.

Note:  Any request body parameters left blank/null (except the password), will be stored in the user account as blank/null.

URL

{BaseURL}/Remote/Account/Update

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
UniqueIdUnique user identifier generated by the DataMotion platform. Also referred to as UIDIntegerY
EmailSecure address of the user on the DataMotion platformStringY
UserIdUser-defined shortened login username that can be used on the DataMotion web portalStringN
SingleSignOnIdUser-defined unique user identifier within a companyStringN
PasswordThe user's passwordStringN
FirstNameFirst name of the userStringN
LastNameLast name of the userStringN
PhonePhone number of the userStringN
CompanyIdThe unique identifier of the user's company on the DataMotion platform. This field will always default to the CompanyId of the Admin accessing the APIIntegerN
EmployeeIdA miscellaneous field (recommended to be used for Employee IDs)StringN
MiscellaneousA miscellaneous fieldStringN
DisabledThis field indicates whether the user account is currently disabled or notBooleanN
UserTypeIdThis field specifies the unique ID of the User’s UserType. A list of UserTypeIds can be obtained by calling GetUserTypesIntegerY
ButtonUserThis field indicates whether the user uses the Outlook button pluginBooleanN
ReceiveOffersThis field indicates whether the User would like to receive offers and updates from DataMotion. The default is falseBooleanN

Request Body Formats

JSON


{
    "UniqueId":,
    "Email":"jane@example.com",
    "UserId":"janetheadmin",
    "SingleSignOnId":"ExampleJane",
    "Password":"|?|Y||p@$5|//0rd",
    "FirstName":"Jane",
    "LastName":"Doe",
    "Phone":"8675309",
    "CompanyId":112,
    "EmployeeId":"1564872",
    "Miscellaneous":"",
    "Disabled":false,
    "UserTypeId":252,
    "ReceiveOffers":false
}

Response Body Values

NameDescriptionType
UniqueIdUnique user identifier generated by the DataMotion platform. Also referred to as UIDInteger
EmailSecure address of the user on the DataMotion platformString
UserIdUser-defined shortened login username that can be used on the DataMotion web portalString
SingleSignOnIdUser-defined unique user identifier within a companyString
PasswordThe user's password. Note: the password field will always be returned blankString
FirstNameFirst name of the userString
LastNameLast name of the userString
PhonePhone number of the userString
CompanyIdThe unique identifier of the user's company on the DataMotion platform. This field will always default to the CompanyId of the Admin accessing the APIInteger
EmployeeIdA miscellaneous field (recommended to be used for Employee IDs)String
MiscellaneousA miscellaneous fieldString
DisabledThis field indicates whether the user account is currently disabled or notBoolean
UserTypeIdThis field specifies the unique ID of the User’s UserType. A list of UserTypeIds can be obtained by calling GetUserTypesInteger
ButtonUserThis field indicates whether the user uses the Outlook button pluginBoolean
ReceiveOffersThis field indicates whether the User would like to receive offers and updates from DataMotion. The default is falseBoolean
ErrorsValidation errors for submitted requestsDictionary<string,List<string>>

Response Body Formats

JSON


{
   "UniqueId":11597,
   "Email":"jane@example.com",
   "UserId":"janetheadmin",
   "SingleSignOnId":"ExampleJane",
   "Password":"|?|Y||p@$5|//0rd",
   "FirstName":"Jane",
   "LastName":"Doe",
   "Phone":"8675309",
   "CompanyId":112,
   "EmployeeId":"1564872",
   "Miscellaneous":"",
   "Disabled":false,
   "UserTypeId":252,
   "UserType":null,
   "ButtonUser":false,
   "ReceiveOffers":false,
   "Errors":{
      "Name":"value",
      "Name":"value"
   }
}
box icon

DELETE A USER ACCOUNT

This method deletes a company user account

URL

{BaseURL}/Remote/Account/Delete

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
UIDUnique user identifier generated by the DataMotion platformIntegerY
EmailSecure address of the user on the DataMotion platformStringY
UserIdUser-defined shortened login username that can be used on the DataMotion web portalStringN
SingleSignOnIdUser-defined unique user identifier within a companyStringN

Request Body Formats

JSON


{
   "UID":11597,
   "Email":"jane@example.com",
   "UserId":"janetheadmin",
   "SingleSignOnId":"ExampleJane"
}

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

box icon

GET USERTYPES

This method provides a list of UserTypes in your company, as well as basic password requirements for these UserTypes.

URL

{BaseURL}/Remote/Account/GetUserTypes

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
TypeIdThe unique identifier of the UserTypeInteger
DescriptionHuman-readable description of the UserTypeString
MinimumPasswordLengthIndicates the minimum number of characters required for a valid password for the UserTypeInteger
RequiredPasswordCategoriesIndicates the minimum number of categories required for a valid password for the UserTypeInteger
CategoriesDescription of categories to be met by RequiredPasswordCategoriesString Array

Response Body Formats

JSON


[
    {
        "TypeId": 252,
        "Description": "Certified Gold Admin",
        "MinimumPasswordLength": 6,
        "RequiredPasswordCategories": 3,
        "Categories": [
            "Lower Case",
            "Upper Case",
            "Numbers",
            "Symbols"
        ]
    },
    {
        "TypeId": 250,
        "Description": "Full User",
        "MinimumPasswordLength": 6,
        "RequiredPasswordCategories": 1,
        "Categories": [
            "Lower Case",
            "Upper Case",
            "Numbers",
            "Symbols"
        ]
    },
    {
        "TypeId": 251,
        "Description": "Secure Contact Us",
        "MinimumPasswordLength": 6,
        "RequiredPasswordCategories": 3,
        "Categories": [
            "Lower Case",
            "Upper Case",
            "Numbers",
            "Symbols"
        ]
    }
]

Gateway

The Gateway API Methods provide the following capabilities:

  • Obtain company-level credentials to authenticate SMTP access for sending emails to the DataMotion SMTP Gateway.
  • Create and maintain a whitelist of IP addresses that are permitted to send emails to the DataMotion SMTP Gateway.
  • Deliver plain text SMTP messages with TLS routing from the DataMotion SMTP Gateway.

box icon

GET COMPANY SMTP CREDENTIALS

This method returns the credentials (Company UserID and Company Password) to access the DataMotion SMTP Gateway on a company authorized level.

URL

{BaseURL}/Remote/SMTP/GetCredentials

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
UserIdUserId for SMTP authorization. Ex: "27______acmeadmin"String
PasswordAuto-generated string used during SMTP authentication. It is 15 characters longString
EndpointsA complex type with the following valuesObject

Response Body Formats

JSON


{
    "UserId": "27______acmeadmin",
    "Password": "iwalkthedog1234",
    "Endpoints": [
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        },
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        }
    ]
}
box icon

RESET PASSWORD

This method generates a new password to be used in SMTP authentication.

URL

{BaseURL}/Remote/SMTP/ResetPassword

HTTP Method

PUT

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should only contain "-1".

Request Body Formats

JSON


{
    -1
}

Response Body Values

NameDescriptionType
UserIdUserId for SMTP authorization. Ex: "27______acmeadmin"String
PasswordAuto-generated string used during SMTP authentication. It is 15 characters longString
EndpointsA complex type with the following valuesObject

Response Body Formats

JSON


{
    "UserId": "27______acmeadmin",
    "Password": "iwalkthedog1234",
    "Endpoints": [
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        },
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        }
    ]
}
box icon

UPDATE IP WHITELIST

This method allows you to establish an exclusive IP whitelist for addresses authorized to connect to the DataMotion SMTP Gateway or to send plain text SMTP messages with TLS routing from the DataMotion SMTP Gateway.

Note:  To remove an existing whitelist, simply pass an emptry string in the request body.

URL

{BaseURL}/Remote/SMTP/PutCredentials

HTTP Method

PUT

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
N/AAn array of SmtpEndpoint2 valuesArrayY

Request Body Formats

JSON


{
    [
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        },
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        }
    ]
}

Response Body Values

NameDescriptionType
UserIdUserId for SMTP authorization. Ex: "27______acmeadmin"String
PasswordAuto-generated string used during SMTP authentication. It is 15 characters longString
EndpointsA complex type with the following valuesObject

Response Body Formats

JSON


{
    "UserId": "27______acmeadmin",
    "Password": "iwalkthedog1234",
    "Endpoints": [
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        },
        {
            "IpAddress": "12.12.12.120",
            "Subnet": "255.255.255.0",
            "Incoming": true,
            "Outgoing": false,
            "Port": 25,
            "Domain": "example.com",
            "Errors": {
                "Field1": [
                    "Field1 is missing",
                    "Field1 is required."
                ],
                "Field2": [
                    "Field2 is missing",
                    "Field2 is required."
                ]
            }
        }
    ]
}

Messaging API

The DataMotion Messaging API facilitates all message handling with various methods for sending, receiving and manipulating a user’s inbox.

Note

The REST-ful Messaging API is currently only available for SecureMail releases 5.37 and up and Direct Secure Messaging releases 6.3 and up. To integrate earlier SecureMail and Direct Secure Messaging releases via API, please see our Helper Libraries & SDKs for any officially supported helper libraries, as well as the original SOAP-based API calls.

Account

The following methods handle authentication to the DataMotion SecureMessagingApi as well as basic account functions.

box icon

GET A SESSION KEY

This method is used to authenticate DataMotion credentials and retrieve a SessionKey. Unless otherwise noted, this method must be called before any any other web service function, as the X-Session-Key header value is required to call most methods.

URL

{BaseURL}/SecureMessagingApi/Account/Logon

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
UserIdOrEmailYour DataMotion UserID or Email AddressStringY
PasswordYour DataMotion passwordStringY

Request Body Formats

JSON


{
    "UserIdOrEmail": "janetA@example.com",
    "Password": "P@ssword1"
}

Response Body Values

NameDescriptionType
SessionKeyThe Session key to be used in future requestsString

Response Body Formats

JSON


{
    "SessionKey": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}
box icon

GET YOUR ACCOUNT DETAILS

This method is used to query account information about the user (like the password expiration date, or how many unread messages are in the user's inbox) based on the SessionKey passed.

URL

{Base URL}/SecureMessagingApi/Account/Details

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
EmailAddressThe email address of the userString
FirstNameThe first name of the userString
LastNameThe last name of the userString
StatisticsA Statistics structure containing the following valuesObject

Response Formats

JSON

{
    "EmailAddress": "janetA@example.com",
    "FirstName": "Janet",
    "LastName": "Anderson",
    "Statistics": {
        "AccountSize": 10240000,
        "AvailableAccountSize": 10209029,
        "DateCreated": "2013-06-24T01:26:00",
        "DateOfLastNotice": "1900-01-01T12:00:00",
        "DateOfLastVisit": "2015-10-28T06:50:00",
        "DatePasswordExpires": "1900-01-01T12:00:00",
        "TotalFilesInOutbox": 0,
        "TotalFilesSent": 0,
        "TotalMessagesInInbox": 10,
        "TotalMessagesInOutbox": 0,
        "TotalMessagesReceived": 103,
        "TotalMessagesSent": 136,
        "TotalUnreadMessagesInInbox": 2,
        "TotalVisits": 5019,
        "UsedAccountSize": 30971
    }
}
box icon

CHANGE YOUR PASSWORD

This method is used to change the password of a user (based on the SessionKey passed). This routine accepts valid DataMotion account credentials and requires a SessionKey parameter.

URL

{Base URL}/SecureMessagingApi/Account/ChangePassword

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
OldPasswordThe old password of the user accountStringY
NewPasswordThe new password you'd like to set for the user accountStringY

Request Formats

JSON


{
    "OldPassword": "OldPassword123",
    "NewPassword": "NewPassword123"
}

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

box icon

LOGOUT

This method is used to invalidate a SessionKey, making any subsequent calls with that SessionKey invalid.

URL

{BaseURL}/SecureMessagingApi/Account/Logout

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

Folder

The following methods describe folder actions.

box icon

LIST ALL FOLDERS

This method is used to retrieve a list of the user’s folders and corresponding statistics.

URL

{BaseURL}/SecureMessagingApi/Folder/List

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
FoldersA Folders structure containing the following values for each folderObject

Response Body Formats

JSON


{
    "Folders": [
    {
        "FolderId": 1,
        "FolderName": "Inbox",
        "FolderType": 0,
        "FolderTypeDescription": "Inbox",
        "IsSystemFolder": true,
        "TotalMessages": 7,
        "TotalSize": 2386
    },
    {
        "FolderId": 3,
        "FolderName": "Track Sent",
        "FolderType": 1,
        "FolderTypeDescription": "Outbox",
        "IsSystemFolder": true,
        "TotalMessages": 3,
        "TotalSize": 30970
    }
]
}
box icon

CREATE A NEW FOLDER

This method is used to create a custom folder in a user’s account. Once a folder is created, messages can be moved into it using the Move Message function.

URL

{BaseURL}/SecureMessagingApi/Folder/

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
FolderNameThe name of the folderStringY
FolderTypeThe integer type of folder. Default is 0.IntegerN

Request Body Formats

JSON


{
    "FolderName": "YourNewFolderName",
    "FolderType": 0
}

Response Body Values

NameDescriptionType
FolderIDThe unique ID of the newly created folderInteger

Response Body Formats

JSON


{
    "FolderId": 12345
}
box icon

DELETE A FOLDER

This method is used to delete a custom folder from a user’s account. Only custom folders can be deleted from a user’s account. When a folder that contains messages is deleted from the system, the messages will be moved into the respective Inbox or Outbox parent folder automatically.

URL

{BaseURL}/SecureMessagingApi/Folder/{FolderID}

Note: The FolderID of the folder you'd like to delete must be passed in the URL of this method

HTTP Method

DELETE

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left emtpy.

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

Message

The following methods handle DataMotion messages.

box icon

GET INBOX MESSAGE IDS

This method is used to retrieve the message IDs (MIDs) of all messages in the user's Inbox.

URL

{BaseURL}/SecureMessagingApi/Message/GetInboxMessageIds

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
FolderIdThe folder ID to search in (must be an inbox folderID). 1 is the primary inbox folder and is the default. -1 represents all inbox folders.IntegerN
MessageListFilterA search parameter. 0(All), 1(Unread), 2(CmLft). 0 is the default.IntegerN
MustHaveAttachmentsA search parameter. If set to true, only messages with attachments will be returnedBooleanN

Request Body Formats

JSON


{
    "FolderId":12345,
    "MessageListFilter":0,
    "MustHaveAttachments":false
}

Response Body Values

NameDescriptionType
MessageIdsAn array of unique message identifiers that correspond to the search parameters givenInteger Array

Response Body Formats

JSON


{
  "MessageIds":  [
    12345678,
    123456789,
    1234567890
  ]
}
box icon

GET MESSAGE SUMMARIES

This method is used to retrieve message summaries of all messages within a specified folder

URL

{BaseURL}/SecureMessagingApi/Message/GetMessageSummaries

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
FolderIdThe ID of the Inbox folder to search (default Inbox Folder ID = 1)IntegerY
LastMessageIDReceivedThe last known message ID recieved. If included, this method will only return messages received after this message ID.IntegerN

Request Body Formats

JSON


{
    "FolderId": 1,
    "LastMessageIDReceived": 64251914
}

Response Body Values

NameDescriptionType
MoreMessagesAvailableIndicates whether there are more messages availableBoolean
SummariesA Summaries structure containing the following values for each messageObject

Response Body Formats

JSON


{
    "MoreMessagesAvailable": false,
    "Summaries": [
        {
          "AttachmentCount": 0,
          "createTimeString": "10/26/2015 1:41:45 PM (UTC-04:00)",
          "FolderId": 1,
          "MessageId": 11542042,
          "MessageSize": 87,
          "Read": false,
          "MessageStatus": 3,
          "SenderAddress": "DougB@example.com",
          "Subject": "Account Details"
        },
        {
          "AttachmentCount": 0,
          "createTimeString": "8/16/2015 1:41:45 PM (UTC-04:00)",
          "FolderId": 1,
          "MessageId": 42511138,
          "MessageSize": 87,
          "Read": false,
          "MessageStatus": 3,
          "SenderAddress": "DougB@example.com",
          "Subject": "Credit Card Information"
        }
    ]
}
box icon

GET UNREAD MESSAGES

This method returns message summaries for all unread messages in the user's Inbox. Any messages that were delivered via SafeTLS (with a MessageStatus = 5) will also be returned in this method.

URL

{BaseURL}/SecureMessagingApi/Message/Inbox/Unread

Optional: Include "?After={LastMessageIDReceived}" to specify the last MessageID received to receive only messages created since the ID reference.

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty

Response Body Values

NameDescriptionType
MoreMessagesAvailableIndicates whether there are more messages availableBoolean
SummariesA Summaries structure containing the following values for each messageObject

Response Body Formats

JSON


{
    "MoreMessagesAvailable": false,
    "Summaries": [
        {
          "AttachmentCount": 0,
          "createTimeString": "10/26/2015 1:41:45 AM (UTC-04:00)",
          "FolderId": 12345,
          "MessageId": 11542042,
          "MessageSize": 87,
          "Read": false,
          "MessageStatus": 3,
          "SenderAddress": "DougB@example.com",
          "Subject": "Account Details"
        },
        {
          "AttachmentCount": 0,
          "createTimeString": "8/16/2015 1:41:45 (UTC-04:00)",
          "FolderId": 12345,
          "MessageId": 42511138,
          "MessageSize": 87,
          "Read": false,
          "MessageStatus": 3,
          "SenderAddress": "DougB@example.com",
          "Subject": "Credit Card Information"
        }
    ]
}
box icon

SEARCH THE INBOX

This method is used to search the user's inbox, based on filter parameters

URL

{BaseURL}/SecureMessagingApi/Message/Inbox/Search

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
FilterThe search criteriaStringN
FolderIdUnique ID of the Inbox folder to search (default Inbox Folder ID = 1)IntegerN
GetInboxUnReadOnlySetting this to true will only return unread messages (Default is false)BooleanN
GetRetractedMsgsSetting this to true will search retracted messages as well (Default is false)BooleanN
OrderByField by which to sort the result setStringN
OrderDescOrder descending (Default is false)BooleanN
PageNumPage number to returnIntegerY
PageSizeNumber of records returned per pageIntegerY

Request Body Formats

JSON


{
    "Filter":"account",
    "FolderId":1,
    "GetInboxUnReadOnly":false,
    "GetRetractedMsgs":false,
    "OrderBy":"",
    "OrderDesc":true,
    "PageNum":1,
    "PageSize":1
}

Response Body Values

NameDescriptionType
PageDetailsA PageDetails structure containing the following valuesObject
ResultsA Results structure containing the following values for each messageObject

Response Body Formats

JSON


{
    "PageDetails": {
        "CurrentPage": 1,
        "FolderId": 1,
        "OrderBy": " DESC",
        "PageSize": 1,
        "TotalMessages": 2,
        "TotalPages": 2
    },
    "Results": [
        {
              "CreateTime": "2014-04-17T08:32:22",
              "LastAction": 0,
              "MessageId": 1022454,
              "MessageSize": 56368,
              "MessageStatusId": 29229679,
              "PasswordHint": "",
              "Read": true,
              "MessageStatus": 4,
              "ReadConfirmation": true,
              "SenderEmail": "BarryK@example.com",
              "SenderId": 5368271,
              "Subject": "Annual Reports"
        }
    ]
}
box icon

GET MESSAGE METADATA

This method is used to retrieve metadata for a sent message, particularly tracking and security information

URL

{BaseURL}/SecureMessagingApi/Message/{MessageId}/Metadata

Note: The MessageId of the message you'd like to retrieve must be passed in the URL of this method

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty

Response Body Values

NameDescriptionType
AttachmentsA complex type containing the Attachment Structure, the SecurityEnvelope Structure, and the Tracking Structure per attachmentObject
ExpirationDateDate/time string for message expirationString
MessageIdUnique message identifierInteger
MessageSizeSize in bytes of messageInteger
SecurityEnvelopeA SecurityEnvelope complex type containing the following valuesObject
TrackingA Tracking complex type containing the following values per recipientObject

Response Body Formats

JSON


{
  "Attachments": [
    {
      "AttachmentId": 12345678,
      "FileName": "file.ext",
      "SecurityEnvelope": {
        "Checksum": "EE26B0DD4AF7E749AA1A8EE3C10AE9923F618980772E473F8819A5D4940E0DB27AC185F8A0E1D5F84F88BC887FD67B143732C304CC5FA9AD8E6F57F50028A8FF",
        "HashAlgorithm": "Sha512",
        "Status": 1,
        "StatusDescription": "Valid"
      },
      "Size": {
        "StdString": "54"
      },
      "Tracking": {
        "Recipients": [
          {
            "ChecksumValidated": 1,
            "Delivered": false,
            "DeliveredDate": "0001/01/01 0:00:00 (UTC-00:00)",
            "Downloaded": true,
            "DownloadedDate": "2017/05/25 16:33:41 (UTC-06:00)",
            "Email": "email@domain.com"
          }
        ]
      }
    }
  ],
  "ExpirationDate": "2015-06-28T04:12:52",
  "MessageId": 12345678,
  "MessageSize": 55,
  "SecurityEnvelope": {
    "Checksum": "1234567890ABCDEFG",
    "HashAlgorithm": "Sha512",
    "Status": 1,
    "StatusDescription": "Valid"
  },
  "Tracking": [
    {
      "DateOpened": "0001-01-01T12:00:00",
      "Email": "kylec@datamotion.com",
      "MessageStatusDescription": "SentSafeTls",
      "MessageStatusId": 5,
      "ReceiverField": "TO"
    }
  ]
}
box icon

GET A MESSAGE

This method retrieves a message based on the MID passed.

URL

{BaseURL}/SecureMessagingApi/Message/{MessageId}

Note: The MessageId of the message you'd like to retrieve must be passed in the URL of this method

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
ToAn array of recipients of the email messageString Array
FromSender's email addressString
CcAn array of recipients carbon copied on the email messageString Array
BccAn array of recipients blind carbon copied on the email messageString Array
SubjectThe subject line of the email messageString
CreateTimeDate/Time string for when message is createdString
AttachmentsA complex type with the following valuesObject
HtmlBodyThe HTML body of the email messageString
TextBodyThe text body of the email messageString

Response Body Formats

JSON


{
    "To":["recipient@example.com"],
    "From":"sender@example.com",
    "Cc":[""],
    "Bcc":[""],
    "Subject":"Account Information",
    "CreateTime":"10/26/2015 1:46:24 AM (UTC-04:00)",
    "Attachments":[{
        "AttachmentBase64":"String content",
        "ContentType":"String content",
        "FileName":"String content"
    }],
    "HtmlBody":"String content",
    "TextBody":"String content"
}
box icon

GET A MIME MESSAGE

This method is used to retrieve a DataMotion message in standard MIME format. Senders and recipients are the only users that have access to the message and will be permitted to retrieve basic DataMotion header information and the Security Envelope. The message sender is the only user that will be permitted to retrieve detailed tracking information. When a message is retrieved using this function, tracking information will automatically be written indicating the message was read by the recipient

URL

{BaseURL}/SecureMessagingApi/Message/{MessageId}/Mime

Note: The MessageId of the message you'd like to get the MIME format of must be passed in the URL of this method

HTTP Method

GET

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
MimeMessageThe well-formed MIME string representation of the messageString

Response Body Formats

JSON


{
    "MimeMessage": "MIME string content here"
}
box icon

SEND A MESSAGE

This method sends a message to a given recipient(s) from the user associated with the SessionKey

URL

{BaseURL}/SecureMessagingApi/Message/

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
ToAn array of recipients of the email messageString ArrayY
FromSender's email addressStringN
CcAn array of recipients carbon copied on the email messageString ArrayN
BccAn array of recipients blind carbon copied on the email messageString ArrayN
SubjectThe subject line of the email messageStringN
CreateTimeDate/Time string for when message is createdStringN
AttachmentsA complex type with the following valuesObjectN
HtmlBodyThe HTML body of the email messageStringN
TextBodyThe text body of the email messageStringN

Request Body Formats

The maximum supported JSON payload size for this method is 15MB. This size limit includes your message and base64-encoded attachments, so we recommend keeping your total attachment size around 10MB or less to account for the ~30% increase in payload size from the base64 attachment encoding.

JSON


{
    "To":["recipient@example.com"],
    "From":"sender@example.com",
    "Cc":["cc@example.com"],
    "Bcc":["bcc@example.com"],
    "Subject":"Sensitive Information",
    "CreateTime":"11:51 AM",
    "Attachments":[{
        "AttachmentBase64":"Base64StringHere",
        "ContentType":"image/jpeg",
        "FileName":"logo.jpeg"
    }],
    "HtmlBody":"String content",
    "TextBody":"String content"
}

Response Body Values

NameDescriptionType
MessageIdThe unique message identifier for the newly created messageInteger

Response Body Formats

JSON


{
  "MessageId": 12345678
}
box icon

SEND A MIME MESSAGE

Sends a properly formatted MIME message.

URL

{BaseURL}/SecureMessagingApi/Message/Mime

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
MimeMessageA well-formed MIME string representation of the message

Note:  If the MIME string is improperly formatted, the message will be saved as a draft
StringY

Request Body Formats

The maximum supported size for your MIME string is 15MB. This size limit includes your message and base64-encoded attachments, so we recommend keeping your total attachment size around 10MB or less to account for the ~30% increase in payload size from the base64 attachment encoding.

JSON


{
    "MimeMessage": "MIME String Here"
}

Response Body Values

NameDescriptionType
MessageIdUnique message identifierInteger

Response Body Formats

JSON


{
  "MessageId": 12345678
}
box icon

MOVE A MESSAGE

This method is used to move a particular message into a specific folder. Messages can only be moved within their respective type (ie: Inbox or Outbox), but they can be placed in any subfolder with the same type.

URL

{BaseURL}/SecureMessagingApi/Message/{MessageId}/Move

Note: The MessageId of the message you'd like to move must be passed in the URL of this method

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

NameDescriptionTypeRequired
DestinationFolderIdThe destination folder's unique identifierIntegerY

Request Body Formats

JSON


{
    "DestinationFolderId": 12345
}

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

box icon

DELETE A MESSAGE

This method is used to delete a message from a folder. When a message is deleted, it's normally moved to a Trash folder and then a Deleted Trash folder before being permanently purged from the DataMotion account. The trash deletion mechanism is controlled by the DataMotion Server. Deleting a message only removes the message from the current user’s account. It does not remove the message from the account of any other DataMotion users referenced in the message.

URL

{BaseURL}/SecureMessagingApi/Message/{MessageId}

Optional URL Parameter: Include "?Permanently=true" to force a message to be permanently deleted from the account, bypassing any Trash folders.

Note:  The MessageId of the message you'd like to delete must be passed in the URL of this method.

HTTP Method

DELETE

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty.

Response Body Values

NameDescriptionType
NewFolderIdThe new Trash folder's unique identifierInteger
ResultsA string messageString

Response Body Formats

JSON


{
    "NewFolderId":2147483647,
    "Result":"String content"
}
box icon

RETRACT A MESSAGE

This method retracts a message from any recipients that have received the message. A message can be retracted whether or not the recipient has read the message, but the message will remain in that user’s account until it expires or the recipient deletes it.

URL

{BaseURL}/SecureMessagingApi/Message/{MessageId}/Retract

Note: The MessageId of the message you'd like to retract must be passed in the URL of this method

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/jsonContent type
X-Session-KeyJA0AH3UFJS0KJASPMB7X0WOSession key

Request Body Parameters

The request body should be left empty

Response Body Values

The response body will be empty, however a successful transaction will receive a 200 status code.

More Information

Errors

The following table lists possible errors that may appear in the responses of the Messaging API methods.

General Errors

Error Text
Bad session key.
SessionKey Expired.
The X-Session-Key header is missing.
User is not authorized to use the Web Service API.

Get a Session Key Errors

Error Text
User credentials are invalid.
User account has not been verified.
User disabled.
Too many invalid logon attempts. User automatically disabled.
User could not be authenticated.
Password expired. User must change their password to use this function.
The LogonRequestData model is required in the request body.
The The UserIdOrEmail field is required.
The Password field is required.

Change Your Password Errors

Error Text
The new password must be at least [MininumLength] characters.
The new password has already been used as one of the last [NumberOfStoredPasswords] passwords.
The new password does not meet complexity requirements.
The new password could not be validated.
The password could not be changed. Please ensure you are using the correct old password.
The ChangePasswordRequestData model is required in the request body.
The NewPassword field is required.
The OldPassword field is required.

Create a New Folder Errors

Error Text
The Folder Type and Folder Name is invalid.
The Folder Name already exists.
The Folder Name is too long.
Folder Type [FolderType] is not supported.
The FolderName field is required.
The CreateFolderRequestData model is required in the request body.
Unknown error while creating folder.

Delete a Folder Errors

Error Text
Folder with ID [FolderId] does not exist.
Folder could not be deleted.
Could not parse the folder ID into an integer.

Get Inbox Message IDs Errors

Error Text
FolderId [FolderId] is not an inbox folder.
MessageList filter [MessageListFilter] is not supported.
FolderId [FolderId] not found.
The InboxMessageIdsSearchOptionsData model is required in the request body

Get Message Summaries Errors

Error Text
An error has occurred at [DateTime] please check the server logs for details.
FolderId [FolderId] not found.
The GetMessageSummariesRequestData model is required in the request body.

Search The Inbox Errors

Error Text
FolderId [FolderId] not found.
Please specify a page size between 1 and 1000.
Folder id [FolderId] is not an inbox folder.
Expected 2 tables from WSGetInboxData but got [NumberOfTables].
The MailboxSearchOptionsData model is required in the request body.
The PageNum field is required.
The PageSize field is required.
Last action [LastAction] is not supported.
Error Text
FolderId [FolderId] not found.
Please specify a page size between 1 and 1000.
Folder id [FolderId] is not an inbox folder.
Expected 2 tables from WSGetOutboxData but got [NumberOfTables].
The MailboxSearchOptionsData model is required in the request body.
The PageNum field is required.
The PageSize field is required.
Last action [LastAction] is not supported.

Get Message Metadata Errors

Error Text
You do not have access to message with id [MessageId].
This message has been deleted from Track Sent and is no longer available.
Could not parse the message ID into an integer.

Get A Message Errors

Error Text
An error has occurred at [DateTime] please check the server logs for details.
You do not have access to message with id [MessageId].
This message has been deleted from Track Sent and is no longer available.
This message has been deleted from the Inbox and is no longer available.
Could not parse the message ID into an integer.

Get A MIME Message Errors

Error Text
You do not have access to message with id [MessageId].
This message has been deleted from Track Sent and is no longer available.
This message has been deleted from the Inbox and is no longer available.
Could not parse the message ID into an integer.

Send A Message Errors

Error Text
At least one recipient must be specified. If you are trying to send a MIME message, please use the SendMimeMessage ({serviceUrl}/Message/Mime) method instead.
Message not sent because you do not have permission to send, or the email address is incorrectly formed for one or more of the recipients specified.
The MessageData model is required in the request body.
The To field is required.
Recipient Invalid - To recipient is [ToEmailAddress].
Recipient Invalid - Cc recipient is [CcEmailAddress].
Recipient Invalid - Bcc recipient is [BccEmailAddress].

Send A MIME Message Errors

Error Text
File sizes >2GB are not supported.
Message not sent because you do not have permission to send or the email address is incorrectly formed for one or more of the recipients specified.
The SendMimeMessageRequestData model is required in the request body.

Move A Message Errors

Error Text
Could not move the message into the destination folder.
The MoveMessageRequestData model is required in the request body.
Could not parse the message ID into an integer.
The DestinationFolderId field is required.
You do not have access to message with id [MessageId].
FolderId [FolderId] is not found.
Message could not be moved to the recovery folder.
Message could not be moved to the trash folder.
This message has been deleted from the Inbox and is no longer available.
This message has been deleted from Track Sent and is no longer available.

Delete A Message Errors

Error Text
Message could not be permanently deleted from the user's account.
Message could not be moved to the recovery folder.
Message could not be moved to the trash folder.
You do not have access to message with id [MessageId]
This message has been deleted from the Inbox and is no longer available.
This message has been deleted from Track Sent and is no longer available.
Could not parse the message ID into an integer.

Retract a Message Errors

Error Text
Message could not be retracted. You may not have permission to retract this message.
Could not parse the message ID into an integer.
You do not have access to message with id [MessageId].
This message has been deleted from the Inbox and is no longer available.
This message has been deleted from Track Sent and is no longer available.

Message Status Definitions

The following table lists the correlations between the delivery or processing state of a message and the integer value associated with it.

Sender-Only Status Types (<=0)

Message StatusValueRead/Unread Status
DirectMessageFailed-8
PendingUpload-7
PendingLicense-6
Pending-5
Restricted-4
Deleted-3
Retracted-2
Draft-1
EditMode0

Sender/Recipient Status Types (>0)

Message StatusValueRead/Unread Status
NoticeInQueue1Unread
NoticeSent2Unread

Per Recipient (not per message) Status Types

Note: When a message is sent to multiple recipients, the message will have a message status ID for each recipient.

Message StatusValueRead/Unread Status
UnRead3Unread
Read4Read

Push Status Types

Message StatusValueRead/Unread Status
SentSafeTls5Read
NoticeError6Unread
Pop3Delivered7Read
PushedZip8Read
SecureFax9Read
PushedPdf10 Read

SecureForms Status Types

Message StatusValueRead/Unread Status
DistributionRequestProcessed11Unread
DistributionRequestFailed12Unread

DataBridge Status Types

Message StatusValueRead/Unread Status
WorkflowDestinationEnroute13Unread
WorkflowDestinationDelivered14Read
WorkflowDestinationUnreachable15Unread

DataMotion Direct Status Types

Message StatusValueRead/Unread Status
DirectMessageQueued16Unread (Tracking)
DirectMessageSent17Unread (Tracking)
DirectMessageDispatched18Unread (Tracking)
DirectMessageProcessed19Unread (Tracking)

More Enumerations

The following lists describe any other enumerations that are used in our Messaging API.

Folder Types

This enumeration can be found in the Folder object of the List All Folders response, as well as the request body for the Create a New Folder method.

  • Inbox = 0
  • Outbox = 1

Checksum Validation Definitions

This enumeration can be found in the SecurityEnvelope object in the response body from the Get Message Metadata method.

  • Invalid = 0
  • Valid = 1
  • Not Applied = 2

Last Action Definitions

This enumeration can be found in the Results object in the response body from the Search the Inbox method.

  • None = 0
  • Replied = 1
  • Forwarded = 2

Provisioning API

This information describes the services available to provision companies on the DataMotion SecureMail platform

Note: The Provisioning API is sometimes referred to as remote manager provisioning web service

box icon

PROVISION A COMPANY

This method can provision, update, or delete a company.

URL

https://provisioning.datamotion.com:8888

HTTP Method

POST

Header Values

KeyValueDescription
X-Emailreseller@example.comThe email address of the reseller account on the DataMotion SecureMail platform
X-IvYj4ij9BV+k484FGvte8PNwInitialization vector used for encryption
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
UserNameA string exactly corresponding to the unique username provided in the provisioning accountStringY
PlatformCodeA string specifying the DataMotion instance that is to be provisionedStringY
CommandAn enumeration specifying Create (1), Update (2), or Cancel (3)IntegerY
IVInitialization vector encoded as a Base64 string used to encrypt the payloadStringY
DataAn encrypted, JSON-serialized string representing the following values and objects.ObjectY
HashA Hash of the Data valuesStringY

Encryption Steps

Your company will be issued a Provisioner Key (also referred to as a Pre-Shared Key or PSK) upon initial onboarding. This Provisioner Key should be kept confidential and access to this key should be regulated by your company. See Libraries & SDKs for encryption examples.



  • 1

    Set up AES Encryption

    Initialize AES encryption with a key length of 256. Using this encryption, generate an Initilization Vector (IV) and encode the IV into a Base64 string. This should be passed as the "X-Iv" header value as well as the "IV" body parameter in the request.
  • 2

    Serialize Payload

    Serialize the payload (unencrypted) as JSON into a byte array.
  • 3

    Get Hash of Payload

    Generate a byte array of your Encryption Key. Using that key, obtain a hash of your unencrypted payload using HMACSHA512. Encode this value into a Base64 string. This should be passed as the "Hash" body parameter value in the request.
  • 4

    Encrypt Payload

    Using AES256, encrypt the byte array from step 2, using your Provisioner Key (as a byte array) and your IV (step 1).

Request Body Formats

Unencrypted JSON


{
    "UserName": "UserName1",
    "PlatformCode": "PlatformCode1",
    "Command": 1,
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": {
        "ReferenceId": "ABCDEFG",
        "CompanyName": "Company Name 1",
        "ExternalIP": "",
        "Status": 0,
        "AutoSenderDomains": [
            "domain1.com",
            "domain2.com"
        ],
        "ExpirationDate": "2008/05/01 18:32:06",
        "Admin": {
            "FirstName": "John",
            "LastName": "Doe",
            "Email": "example@email.com",
            "PhoneNumber": "5555555555"
        },
        "BillingInterval": {
            "Monthly": false,
            "Years": 1
        },
        "UserTypes": [
            {
                "UserTypeCode": "123",
                "LicenseQuantity": 5
            },
            {
                "UserTypeCode": "321",
                "LicenseQuantity": 10
            }
        ],
        "Cobrand": {
            "Url": "example.com",
            "Color": "#ff00ff",
            "Logo": "",
            "LogoFileName": "",
            "SecureContacts": [
                {
                    "UserTypeCode": "123",
                    "DisplayName": "Sales",
                    "Email": "sales@example.com"
                },
                {
                    "UserTypeCode": "321",
                    "DisplayName": "Support",
                    "Email": "support@example.com"
                }
            ]
        }
    },
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Encrypted JSON


{
    "UserName": "UserName1",
    "PlatformCode": "PlatformCode1",
    "Command": 1,
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": "JIWEHR932WHRWSDIUFSDHJK",
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Response Body Parameters

NameDescriptionType
TransactionIdRemote manager service's unique ID for the transaction processedString
ErrorsEnumerated list of errors. Any errors with one entry containing a 0 indicates successful processing click hereList (enum)
IVInitialization vector encoded as a Base64 string used to encrypt the payloadString
DataAn encrypted, JSON-serialized string representing the server's responseString
HashA Hash of the Data valuesString

Decryption Steps

Your company will be issued a Provisioner Key (also referred to as a Pre-Shared Key or PSK) upon initial onboarding. This Provisioner Key should be kept confidential and access to this key should be regulated by your company. See Libraries & SDKs for encryption examples.



  • 1

    Set up AES Encryption

    Initialize AES encryption with a key length of 256, using the Initialization Vector from the "IV" response body parameter.
  • 2

    Decrypt Payload

    Using AES256, decrypt the "Data" response body parameter received from the server using your Provisioner Key (as a byte array) and your IV (step 1).
  • 3

    Deserialize Payload

    Deserialize the payload (unencrypted) with new "Data" value (step 2) into an object.
  • 4

    Compare Hash of Payload

    Get a hash of the "Data" value (step 2) and compare to the "Hash" response body parameter returned from the server. If the hashes match, the response is authentic. If the hashes do not match, the response should be rejected.

Response Body Formats

Encrypted JSON


{
    "TransactionId":"123kjsadhgf",
    "Errors":[0],
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": "JIWEHR932WHRWSDIUFSDHJK",
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Unencrypted JSON


{
    "TransactionId":"123kjsadhgf",
    "Errors":[0],
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": {
        "ReferenceId": "ABCDEFG",
        "CompanyName": "Company Name 1",
        "ExternalIP": "",
        "Status": 0,
        "AutoSenderDomains": [
            "domain1.com",
            "domain2.com"
        ],
        "ExpirationDate": "2008/05/01 18:32:06",
        "Admin": {
            "FirstName": "John",
            "LastName": "Doe",
            "Email": "example@email.com",
            "PhoneNumber": "5555555555"
        },
        "BillingInterval": {
            "Monthly": false,
            "Years": 1
        },
        "UserTypes": [
            {
                "UserTypeCode": "123",
                "LicenseQuantity": 5
            },
            {
                "UserTypeCode": "321",
                "LicenseQuantity": 10
            }
        ],
        "Cobrand": {
            "Url": "example.com",
            "Color": "#ff00ff",
            "Logo": "",
            "LogoFileName": "",
            "SecureContacts": [
                {
                    "UserTypeCode": "123",
                    "DisplayName": "Sales",
                    "Email": "sales@example.com"
                },
                {
                    "UserTypeCode": "321",
                    "DisplayName": "Support",
                    "Email": "support@example.com"
                }
            ]
        }
    },
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}
box icon

GET AN ENCRYPTION KEY (PSK)

This method returns a user's encryption key associated with a provided AutomationId. If no AutomationId is provided, this method will return the default encryption key for the company.

URL

https://provisioning.datamotion.com:8888/company/GetEncryptionKey

HTTP Method

POST

Header Values

KeyValueDescription
X-Emailreseller@example.comThe email address of the reseller account on the DataMotion SecureMail platform
X-IvYj4ij9BV+k484FGvte8PNwInitialization vector used for encryption
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
UserNameA string exactly corresponding to the unique username provided in the provisioning accountStringY
PlatformCodeA string specifying the DataMotion instance that is to be provisionedStringY
IVInitialization vector encoded as a Base64 string used to encrypt the payloadStringY
DataAn encrypted, JSON-serialized string representing the following valuesObjectY
HashA Hash of the Data valuesStringY

Encryption Steps

Follow the same Encryption Steps found in the Provision method

Request Body Formats

Unencrypted JSON


{
    "UserName": "UserName1",
    "PlatformCode": "PlatformCode1",
    "Command": 1,
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": {
        "ReferenceId":"ABCDEFG",
        "AutomationId":"ExampleCompanyString"
    },
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Encrypted JSON


{
    "UserName": "UserName1",
    "PlatformCode": "PlatformCode1",
    "Command": 1,
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": "JIWEHR932WHRWSDIUFSDHJK",
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Response Body Parameters

NameDescriptionType
TransactionIdRemote manager service's unique ID for the transaction processedString
ErrorsEnumerated list of errors. Any errors with one entry containing a 0 indicates successful processingList (enum)
IVInitialization vector encoded as a Base64 string used to encrypt the payloadString
DataAn encrypted, JSON-serialized string representing the server's responseString
HashA Hash of the Data valuesString

Decryption Steps

Follow the same Decryption Steps found in the Provision method

Response Body Formats

Encrypted JSON


{
    "TransactionId":"123kjsadhgf",
    "Errors":[0],
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": "JIWEHR932WHRWSDIUFSDHJK",
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Unencrypted JSON


{
    "TransactionId":"123kjsadhgf",
    "Errors":[0],
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": {
        "ReferenceId":"ABCDEFG",
        "AutomationId":"ExampleCompanyString",
        "ApiEncryptionKey":"KJHAS9AKJSh39"
    },
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}
box icon

CREATE A NEW ENCRYPTION KEY (PSK)

This method generates and returns a new user encryption key if an AutomationId is provided, thus invalidating any existing keys. If an AutomationId is not provided, a new AutomationId will also be generated.

URL

https://provisioning.datamotion.com:8888/company/NewEncryptionKey

HTTP Method

POST

Header Values

KeyValueDescription
X-Emailreseller@example.comThe email address of the reseller account on the DataMotion SecureMail platform
X-IvYj4ij9BV+k484FGvte8PNwInitialization vector used for encryption
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
UserNameA string exactly corresponding to the unique username provided in the provisioning accountStringY
PlatformCodeA string specifying the DataMotion instance that is to be provisionedStringY
IVInitialization vector encoded as a Base64 string used to encrypt the payloadStringY
DataAn encrypted, JSON-serialized string representing the following valuesObjectY
HashA Hash of the Data valuesStringY

Encryption Steps

Follow the same Encryption Steps found in the Provision method

Request Body Formats

Unencrypted JSON


{
    "UserName": "UserName1",
    "PlatformCode": "PlatformCode1",
    "Command": 1,
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": {
        "ReferenceId":"ABCDEFG",
        "AutomationId":"ExampleCompanyString"
    },
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Encrypted JSON


{
    "UserName": "UserName1",
    "PlatformCode": "PlatformCode1",
    "Command": 1,
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": "JIWEHR932WHRWSDIUFSDHJK",
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Response Body Parameters

NameDescriptionType
TransactionIdRemote manager service's unique ID for the transaction processedString
ErrorsEnumerated list of errors. Any errors with one entry containing a 0 indicates successful processing $$CLICK HERE$$List (enum)
IVInitialization vector encoded as a Base64 string used to encrypt the payloadString
DataAn encrypted, JSON-serialized string representing the server's responseString
HashA Hash of the Data valuesString

Decryption Steps

Follow the same Decryption Steps found in the Provision method

Response Body Formats

Encrypted JSON


{
    "TransactionId":"123kjsadhgf",
    "Errors":[0],
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": "JIWEHR932WHRWSDIUFSDHJK",
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

Unencrypted JSON


{
    "TransactionId":"123kjsadhgf",
    "Errors":[0],
    "IV": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "Data": {
        "ReferenceId":"ABCDEFG",
        "AutomationId":"ExampleCompanyString",
        "ApiEncryptionKey":"KJHAS9AKJSh39"
    },
    "Hash": "LIUWJEDFGH807WGBKERBWOERJGH"
}

More Information

Error Codes

The following table lists possible errors that may appear in the responses of the Provisioning API methods.

Company Errors

Error NameError Description
CouldNotCreateCompanyThe company could not be created for a reason not listed elsewhere
CompanyNotFoundThe company name did not match any existing company when attempting to update the company
CompanyTypeNotFoundThe company type was not found when attempting to create the company
CompanyNameAlreadyExistsThe company name matched an existing company when attempting to create the company
DomainAlreadyRegisteredAn attempt to associate an AutoSenderDomain with the company failed as the domain is already associated with another company
UnableToRegisterDomainAn error occurred while attempting to register a domain but the domain is not neccessarily already registered
ReferenceIdAlreadyUsedThis error will occur when trying to create a new company with a previously used ReferenceId
UnknownCompanyStatusA status other than 0, 1, or 2 ("Active", "Trial", or "Cancelled") was specified
BillingPeriodInvalidEither: Monthly = true and Years < > 0, or Monthly = false and Years is not greater than or equal to 1
PastExpirationDateThe date supplied in the request is in the past

Admin Errors

Error NameError Description
CouldNotCreateAdminThe administrative user could not be created for a general reason. This error will be accompanied with a User Error listed below

User Errors

Error NameError Description
CouldNotLoadUserIndicates an existing user could not be loaded
UserNotInCompanyTrying to update a user whose email address already exists in another company
CouldNotAddUserToUserTypeMay occur if a user is already registered as a paid user or in the administrative role
CouldNotUpdateUserThis error should be accompanied by a more specific error message as to why the user could not be updated
CouldNotCreateUserGeneral error
InvalidUserIdThe ID used to identify the user is invalid
ErrorDeletingUserThis error should be accompanied by a more specific error message as to why the user could not be deleted
InvalidEmailAddressThe supplied email does not follow a standard name@domain.com well-formed format

UserType Errors

Error NameError Description
TemplateNotFoundThe UserType feature set could not be found
UserTypeNotFoundThe specified UserType is not a valid selection
LicenseQuantityLessThanNumberOfUsersThe requested LicenseQuantity update count is less that the current number of users already provisioned for that UserType
CouldNotCreateTypeThe instance could not create the feature set
ErrorDeletingUserTypeAn error occured while rolling back a failed transaction. This error should be accompanied by a more specific error message as to why the transaction needed to be rolled back

Cobrand Errors

Error NameError Description
CouldNotCreateCobrandCobrand could not be created for a general reason not listed below
IncompleteCobrandDataAll cobrand data, with the exception of SecureContacts, is required upon creation or update
CobrandExistsAnother company with the same first 8 characters already exists with a cobranded portal
UnableToProcessCobrandLogoThis is a system error
MoreSecureContactsThanLicensesThe number of requested SecureContacts exceeds the amount of available licenses for the UserType specified
SecureContactProvisioningNotAllowedNone of the UserType feature sets provisioned for this company include SecureContact functionality
SecureContactRequiresCobrandProvisioning a SecureContact requires a cobrand be specified

Other Errors

Error NameError Description
NotAuthorizedThe UserName supplied is invalid
BadCryptoSupplied Hash does not match computed Hash
InvalidPlatformNameThe supplied value does not match a DataMotion instance that the user is authorized to provision
UnknownCommandA Command other than "Create" (1), "Update" (2), or "Cancel" (3) was supplied
ErrorConnectingToRemotePlatformThe DataMotion instance was non-responsive
InvalidDateThe ExpirationDate either: is improperly formatted (mm/dd/yyyy), contains an invalid month (ie: <1 or >12 ), contains an invalid day (ie: <1 or >31), or specifies a day that is invalid in combination with the month
MalformedJsonStringThe decrypted Data string is incorrectly formatted or serialized
UnknownErrorGeneric catch-all