Common Direct Messaging 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.

Direct Provisioning API

This information describes the services available to programmatically provision users through the DataMotion Direct Provisioning Portal (DPP).

Certificate Management

The following methods give programmatic access to administer and manager certificates on the DPP.

box icon

REQUEST AN ORGANIZATIONAL CERTIFICATE

This method is used by Trusted Agents, or TAs, to submit a certificate application to a DataMotion Officer for review. Once a DataMotion Officer reviews the certificate application, an Organizational Certificate (org cert) will be generated and installed.

URL

{BaseURL}/DirectProvisioningApi/Certificate/Organizational

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
TrustedAgentThe TA to be named on the certificate applicationStringY
OrganizationNameThe legal business name of the organization, as established in the DPPStringY
OrganizationCategoryThe HIPAA-compliance type for the organization (HIPAABusinessAssociate = 3, HIPAACoveredEntity = 2, Other = 1)EnumerationY
CityThe city where the Organization is locatedStringY
StateThe state where the Organization is locatedStringY
CountryThe country where the Organization is locatedStringY
LifetimeThe duration of the certificate with allowed values of 1, 2, or 3 yearsIntegerY
CommonNameThe Direct-specific (sub)domain to which the certificate shall be boundStringY
SubjectAltNameThe Direct-specific (sub)domain to which the certificate shall be boundStringY
AutoRenewIndicates whether or not the certificate should be automatically renewed upon expirationBooleanY
DelegatedIdProofingIndicates that the TA accepts responsibility that the identity of users covered by this certificate will have to be (if not already) vettedBooleanY
NotesAny notes to submit to the DataMotion Officer to review with the certificate applicationStringN

Request Body Formats

JSON


{
     "TrustedAgent":"JohnTrust@example.com",
     "OrganizationName":"MyTown Medical Center",
     "OrganizationCategory":"2",
     "City":"MyTown",
     "Country":"US",
     "Lifetime":"2",
     "CommonName":"direct.mytowndocs.com",
     "SubjectAltName":"direct.mytowndocs.com",
     "AutoRenew":true,
     "DelegateIdProofing":true,
     "Notes":"",
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage (string) and RequestId (integer)

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\",\"RequestId\":12345}"
 }
box icon

REQUEST AN ADDRESS CERTIFICATE

This method is used by Trusted Agents, or TAs, to submit a certificate application to a DataMotion Officer for review. Once a DataMotion Officer reviews and approves the certificate application, an Address Certificate (address cert) will be generated and installed, and the Direct Address bound to the address cert will be provisioned on the DataMotion HISP.

URL

{BaseURL}/DirectProvisioningApi/Certificate/Address

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
TrustedAgentThe TA to be named on the certificate applicationStringY
OrganizationNameThe legal business name of the organization, as established in the DPPStringY
OrganizationCategoryThe HIPAA-compliance type for the organization (HIPAABusinessAssociate = 3, HIPAACoveredEntity = 2, Other = 1)EnumerationY
FirstNameThe first name of the certificate recipientStringY
LastNameThe last name of the certificate recipientStringY
CityThe city where the certificate recipient is locatedStringY
StateThe state where the certificate recipient is locatedStringY
CountryThe country where the certificate recipient is locatedStringY
LifetimeThe duration of the certificate with allowed values of 1, 2, or 3 yearsIntegerY
CommonNameThe first and last name of the certificate recipientStringY
SubjectAltNameThe Direct messaging address for which the certificate request is createdStringY
PasswordThe password for this user's Direct messaging accountStringN
AutoRenewIndicates whether or not the certificate should be automatically renewed upon expirationBooleanY
DelegatedIdProofingIndicates that the TA accepts responsibility that the identity of the individual covered by this certificate has been fully vetted to LoA3 standardsBooleanY
EmailAddressThe notification address to be used in provisioning, not for the certificateStringY
NotesAny notes to submit to the DataMotion Officer to review with the certificate applicationStringN
Address1The first line of the practice address of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
Address2The second line of the practice address (ie: Suite #, Floor, etc) of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
ZipCodeThe zip code of the practice address of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
PhoneThe phone number of the practice of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
FaxThe fax number of the practice of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
NPIThe NPI of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
OrgNPIThe organizational NPI (ie: the NPI of the practice) of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
SpecialtyThe specialty of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN
RoleThe role of the certificate recipient, to be used in the DataMotion Healthcare Provider DirectoryStringN

Request Body Formats

JSON


{
     "TrustedAgent":"JohnTrust@example.com",
     "OrganizationName":"MyTown Medical Center",
     "OrganizationCategory":"2",
     "FirstName":"Helen",
     "LastName":"Jones",
     "City":"MyTown",
     "State":"NY",
     "Country":"US",
     "Lifetime":"2",
     "CommonName":"Helen Jones",
     "SubjectAltName":"HelenJonesMD@direct.mytowndocs.com",
     "Password":"Password123",
     "AutoRenew":true,
     "DelegateIdProofing":true,
     "EmailAddress":"helenjones123@personalemail.com",
     "Notes":"",
     "Address1":"123 Doctor Blvd",
     "Address2":"Suite 1",
     "ZipCode":"12345",
     "Phone":"5551234567",
     "Fax":"5551234568",
     "NPI":"1234567890",
     "OrgNPI":"1234567899",
     "Specialty":"Internal Medicine",
     "Role":"MD",
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage (string) and RequestId (integer)

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\",\"RequestId\":12345}"
 }
box icon

REQUEST A PATIENT CERTIFICATE

This method is used by Trusted Agents, or TAs, to submit a certificate application to a DataMotion Officer for review. Once a DataMotion Officer reviews and approves the certificate application, a Patient Certificate (patient cert) will be generated and installed, and the Direct Address bound to the patient cert will be provisioned on the DataMotion HISP.

URL

{BaseURL}/DirectProvisioningApi/Certificate/Patient

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
TrustedAgentThe TA to be named on the certificate applicationStringY
OrganizationNameThe legal business name of the organization to which the patient belongs, as established in the DPPStringY
OrganizationCategoryThe HIPAA-compliance type for the organization (4 = Patient)EnumerationY
FirstNameThe first name of the patientStringY
LastNameThe last name of the patientStringY
CityThe city where the patient is locatedStringY
StateThe state where the patient is locatedStringY
CountryThe country where the patient is locatedStringY
LifetimeThe duration of the certificate with allowed values of 1, 2, or 3 yearsIntegerY
CommonNameThe first and last name of the patientStringY
SubjectAltNameThe Direct messaging address to be created for the patientStringY
PasswordThe password for this user's Direct messaging accountStringN
AutoRenewIndicates whether or not the certificate should be automatically renewed upon expirationBooleanY
DelegatedIdProofingIndicates that the TA accepts responsibility that the identity of the patient covered by this certificate has been fully vetted to LoA3 standardsBooleanY
EmailAddressThe notification address to be used in provisioning, not for the certificateStringY
NotesAny notes to submit to the DataMotion Officer to review with the certificate applicationStringN

Request Body Formats

JSON


{
     "TrustedAgent":"JohnTrust@example.com",
     "OrganizationName":"MyTown Medical Center",
     "OrganizationCategory":"2",
     "FirstName":"Helen",
     "LastName":"Jones",
     "City":"MyTown",
     "State":"NY",
     "Country":"US",
     "Lifetime":"2",
     "CommonName":"Helen Jones",
     "SubjectAltName":"HelenJonesMD@direct.mytowndocs.com",
     "Password":"Password123",
     "AutoRenew":true,
     "DelegateIdProofing":true,
     "EmailAddress":"helenjones123@personalemail.com",
     "Notes":"",
     "Address1":"123 Doctor Blvd",
     "Address2":"Suite 1",
     "ZipCode":"12345",
     "Phone":"5551234567",
     "Fax":"5551234568",
     "NPI":"1234567890",
     "OrgNPI":"1234567899",
     "Specialty":"Internal Medicine",
     "Role":"MD",
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage (string) and RequestId (integer)

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\",\"RequestId\":12345}"
 }
box icon

REVOKE A CERTIFICATE

This method is used by Trusted Agents, or TAs, to submit a certificate revocation request to a DataMotion Officer for review. Once a DataMotion Officer reviews and approves the certificate request, the specified certificate will be revoked and uninstalled. Any addresses bound to the certificate will lose functionality.

URL

{BaseURL}/DirectProvisioningApi/Certificate/Revocation

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
DirectAddressOrDomainEither the Direct Address or the domain bound to the certificate to revokeStringY
RevocationReasonAn Enumeration of the following valuesEnumY

Request Body Formats

JSON


{
     "DirectAddressOrDomain":"direct.mytowndocs.com",
     "RevocationReason":"1"
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage (string) and RequestId (integer)

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\",\"RequestId\":12345}"
 }
box icon

CHECK CERTIFICATE STATUS

This method is used by Trusted Agents, or TAs, to check on the status of a certificate request.

URL

{BaseURL}/DirectProvisioningApi/Certificate/Status

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
RequestIdThe RequestId received in the response of the original certificate requestIntegerY

Request Body Formats

JSON


{
     "RequestId": 123456,
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage and CertificateRequestStatus

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\",\"CertificateRequestStatus\":0}"
}

Users Requests

The following methods give programmatic access to administer and manager user accounts on the DPP.

box icon

PROVISION A USER (UNDER AN ORG CERT)

This method is used by Trusted Agents, or TAs, to programmatically provision Direct addresses for users covered by Organizational Certificates (Org Certs).

Note: To provision users not covered by Org Certs, please see Requesting an Address Cert or Requesting a Patient Cert

URL

{BaseURL}/DirectProvisioningApi/User/Provisioning

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
OrganizationNameThe legal business name of the organization, as established in the DPP, that the user belongs toStringY
DirectAddressThe desired Direct address to be provisioned for the userStringY
ContactEmailThe notification address of the userStringY
FirstNameThe first name of the userStringY
LastNameThe last name of the userStringY
Address1The first line of the practice address of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
Address2The second line of the practice address (ie: Suite #, Floor, etc) of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
CityThe city where the user's practice is located, to be used in the DataMotion Healthcare Provider DirectoryStringY
StateThe state where the user's practice is located, to be used in the DataMotion Healthcare Provider DirectoryStringY
ZipCodeThe zip code of the practice address of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
PhoneThe phone number of the practice of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
FaxThe fax number of the practice of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
NPIThe NPI of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
OrgNPIThe organizational NPI (ie: the NPI of the practice) of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
SpecialtyThe specialty of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN
RoleThe role of the user, to be used in the DataMotion Healthcare Provider DirectoryStringN

Request Body Formats

JSON


{
     "OrganizationName":"MyTown Medical Center",
     "DirectAddress":"example@direct.mytownmedcenter.com",
     "ContactEmail":"helenjones123@personalemail.com",
     "FirstName":"Helen",
     "LastName":"Jones",
     "Address1":"123 Doctor Blvd",
     "Address2":"Suite 1",
     "City":"MyTown",
     "State":"NY",
     "ZipCode":"12345",
     "Phone":"5551234567",
     "Fax":"5551234568",
     "NPI":"1234567890",
     "OrgNPI":"1234567899",
     "Specialty":"Internal Medicine",
     "Role":"MD",
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage (string)

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\"}"
}
box icon

DELETE A USER

This method is used by Trusted Agents, or TAs, to delete a user from the DataMotion HISP.

URL

{BaseURL}/DirectProvisioningApi/User/Deletion

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
DirectAddressThe Direct Address of the user to be deletedStringY

Request Body Formats

JSON


{
     "DirectAddress":"Example@direct.example.com",
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage (string)

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\"}"
}
box icon

CHECK A USER'S PROVISIONING STATUS

This method is used by Trusted Agents, or TAs, to submit a certificate application to a DataMotion Officer for review. Once a DataMotion Officer reviews and approves the certificate application, a Patient Certificate (patient cert) will be generated and installed, and the Direct Address bound to the patient cert will be provisioned on the DataMotion HISP.

URL

{BaseURL}/DirectProvisioningApi/User/Status

HTTP Method

POST

Header Values

KeyValueDescription
X-User-Idexample@email.comThe email/username of the TA as established on the DPP
X-User-PasswordPassword123The password of the TA as established on the DPP
Content-Typeapplication/jsonContent type

Request Body Parameters

NameDescriptionTypeRequired
TrustedAgentThe TA to be named on the certificate applicationStringY
OrganizationNameThe legal business name of the organization to which the patient belongs, as established in the DPPStringY
OrganizationCategoryThe HIPAA-compliance type for the organization (4 = Patient)EnumerationY
FirstNameThe first name of the patientStringY
LastNameThe last name of the patientStringY
CityThe city where the patient is locatedStringY
StateThe state where the patient is locatedStringY
CountryThe country where the patient is locatedStringY
LifetimeThe duration of the certificate with allowed values of 1, 2, or 3 yearsIntegerY
CommonNameThe first and last name of the patientStringY
SubjectAltNameThe Direct messaging address to be created for the patientStringY
AutoRenewIndicates whether or not the certificate should be automatically renewed upon expirationBooleanY
DelegatedIdProofingIndicates that the TA accepts responsibility that the identity of the patient covered by this certificate has been fully vetted to LoA3 standardsBooleanY
EmailAddressThe notification address to be used in provisioning, not for the certificateStringY
NotesAny notes to submit to the DataMotion Officer to review with the certificate applicationStringN

Request Body Formats

JSON


{
     "DirectAddress":"Example@direct.example.com"
 }

Response Body Values

NameDescriptionType
ErrorsList of enumerated codesIndicates one or more problems occurred by the web service. Any Errors with a one-list entry containing a 0 value indicates that the transaction was processed successfully.
DataObjectA serialized object containing the ResponseMessage and UserRequestStatus

Response Body Formats

JSON


{
     "Errors": [
       0
     ],
     "Data": "{\"ResponseMessage\":\"Transaction request was successful\",\"UserRequestStatus\":12345}"
 }

HPD Search API

This information describes the services available to utilize the Healthcare Provider Directory (HPD) on the DataMotion Direct platform

box icon

GET A SESSION KEY

This method is used to authenticate DataMotion credentials and retrieve a SessionKey.

Note:  A SessionKey obtained from any other DataMotion web services (ie: Admin API, Messaging API) can be used in place of the HPD Login method. This method is simply provided as a convenience to developers integrating with only the HPD Search API.

URL

{BaseURL}/HpdProxyApi/Logon

HTTP Method

POST

Header Values

KeyValueDescription
Content-Typeapplication/x-www-form-urlencodedContent type

Request Body Parameters

NameDescriptionTypeRequired
userIdYour DataMotion UserID or Email AddressStringY
passwordYour DataMotion passwordStringY

Request Body Formats

UrlEncoded


userId=UserNameExample&password=Password123

Response Body Values

NameDescriptionType
SessionKeyThe Session key to be used in future requestsInteger
MustVerifyIndicates whether the user needs to set their password/validate their email addressBoolean

Response Body Formats

JSON


{
    "Value": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "MustVerify": false
}

Direct Messaging API

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

Account

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

box posicon

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 Direct Address or UserIDStringY
PasswordYour DataMotion Direct passwordStringY

Request Body Formats

JSON


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

Response Body Values

NameDescriptionType
SessionKeyThe Session key to be used in future requestsInteger

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 does not require a SessionKey parameter. As such, ChangePassword allows an account password to be changed even if the account’s password has expired.

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 folderIntegerY

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

GET

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)IntegerY
MessageStatusIdsAn array of message status IDs to be searchedStringN
MustHaveAttachmentsA search parameter. If set to true, only messages with attachments will be returnedBooleanY

Request Body Formats

JSON


{
    "FolderId":12345,
    "MessageStatusIds":[1],
    "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 criteriaStringY
FolderIdID of the Inbox folder to search (default Inbox Folder ID = 1)IntegerY
GetInboxUnReadOnlySetting this to true will only return unread messagesBooleanN
GetRetractedMsgsSetting this to true will search retracted messages as wellBooleanN
OrderByField by which to sort the result setStringN
OrderDescOrder descriptionBooleanN
PageNumPage number to returnIntegerN
PageSizeNumber of records returned per pageIntegerN

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": [],
  "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/27/15 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 identifiers 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

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
ResultOne of the following: "Messsage successfully deleted from folder and moved to the trash folder.", "Message successfully deleted from the trash folder and moved to the deleted trash folder.", "Message successfully deleted permanently." String

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.

Group Mailboxes

The DataMotion Direct group mailbox configuration provides the ability to delegate other Direct accounts within your company to access and respond to messages on your behalf. These methods make it easy to programmatically manage delegate accounts and group mailbox configurations

box icon

ADD A DELEGATE ACCOUNT

This method allows a group mailbox owner to add a delegate from their organization

URL

{BaseURL}/SecureMessagingApi/Folder/Delegates

HTTP Method

PUT

Header Values

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

Request Body Parameters

NameDescriptionTypeRequired
DelegateAddressThe Direct address of the user who will be delegated access to your inboxStringY

Request Body Formats

JSON


{
    "DelegateAddress": "receptionist@direct.hospital.com"
}

Response Body Values

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

box icon

SHOW ALL DELEGATES

This method is used to retrieve all delegate addresses for a user's inbox

URL

{BaseURL}/SecureMessagingApi/Folder/Delegates

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
DelegatesAn array of objects containing these values for each messageObject Array

Response Body Formats

JSON


{
    "Delegates": [
        {
          "DelegateAddress": receptionist@direct.hospital.com,
          "Created": "5/3/2017 2:04:00 PM"
        },
        {
          "DelegateAddress": "billing@direct.hospital.com",
          "Created": "5/3/2017 2:05:00 PM"
        }
    ]
}
box icon

DELETE A DELEGATE ACCOUNT

This method allows a mailbox owner to delete a delegate account and remove their access to the group mailbox. This method does not delete any addresses from the system

URL

{BaseURL}/SecureMessagingApi/Folder/{DelegateAddress}/Delegates

Note: You must pass the DelegateAddress of the delegate whose access you'd like to revoke 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

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

box icon

SHOW GROUPBOX MEMBERSHIP

This method allows a delegate to view their group mailbox membership (ie: which groupboxes the user has access to). If the user is not a delegate for any group mailboxes, the response will be empty

URL

{BaseURL}/SecureMessagingApi/Folder/GroupBox

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
GroupBoxesAn array of objects containing these values for each messageObject Array

Response Body Formats

JSON


{
    "GroupBoxes": [
        {
          "GroupBoxAddress": receptionist@direct.hospital.com,
          "Created": "5/3/2017 2:04:00 PM"
        },
        {
          "GroupBoxAddress": "billing@direct.hospital.com",
          "Created": "5/3/2017 2:05:00 PM"
        }
    ]
}
box icon

GET GROUP INBOX MESSAGE IDS

This method returns message IDs from the group inbox matching the search criteria

URL

{BaseURL}/SecureMessagingApi/Message/GetGroupMessageIds

HTTP Method

POST

Header Values

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

Request Body Parameters

NameDescriptionTypeRequired
MustHaveAttachmentsIndicates whether to return only messages with an attachmentBooleanY

Request Body Formats

JSON


{
    "MustHaveAttachments": false
}

Response Body Values

NameDescriptionType
MessageIdsA list of message IDsArray

Response Body Formats

JSON


{
    "MessageIds": [123,234,345]
}
box icon

GET GROUP MESSAGE SUMMARIES

Get message summaries. Can be limited by folder and by messages newer than an optionally supplied message ID to only get summaries for recent messages

URL

{BaseURL}/SecureMessagingApi/Message/GetGroupMessageSummaries

HTTP Method

POST

Header Values

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

Request Body Parameters

NameDescriptionTypeRequired
LastMessageIdReceivedOptional parameter to limit results to only return messages newer than this MIDIntegerN

Request Body Formats

JSON


{
    "LastMessageIdReceived": 12345
}

Response Body Values

NameDescriptionType
MoreMessagesAvailableIndicates if more messages are availableBoolean
MessageIdUnique message identifierInteger
SubjectThe subject of the messageString
CreatedThe date the message was createdString
FromAddressThe sender of the messageString
ToAddressThe recipient of the message (the group mailbox owner)String
SizeThe size of the messageLong
MessageStatusThe status of the messageInteger

Response Body Formats

JSON


{
    "MoreMessagesAvailable": false,
    "Summaries": [{
      "MessageId": 1234,
      "Subject": "String content",
      "Created": "String content",
      "FromAddress": "String content",
      "ToAddress": "String content",
      "Size": "String content",
      "MessageStatus": 0
    }]
}
box icon

GET GROUP INBOX

Get message summaries from the group inbox. Can be limited to messages newer than an optionally supplied message ID to only get summaries for recent messages.

URL

{BaseURL}/SecureMessagingApi/Message/GroupInbox?After={LastMessageIdReceived}

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 Formats

JSON


{
    "MoreMessagesAvailable": false,
    "Summaries": [{
      "MessageId": 1234,
      "Subject": "String content",
      "Created": "String content",
      "FromAddress": "String content",
      "ToAddress": "String content",
      "Size": 123,
      "MessageStatus": 0
    }]
}
box icon

GET UNREAD GROUP INBOX MESSAGES

Get summaries of all unread messages in the group inbox. Optionally, specify the last message ID received to receive only messages created since the ID referenced.

URL

{BaseURL}/SecureMessagingApi/Message/GroupInbox/Unread?After={LastMessageIdReceived}

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 if more messages are availableBoolean
SummariesA Summaries structure containing the following valuesObject

Response Body Formats

JSON


{
    "MoreMessagesAvailable": false,
    "Summaries": [{
      "MessageId": 1234,
      "Subject": "String content",
      "Created": "String content",
      "FromAddress": "String content",
      "ToAddress": "String content",
      "Size": 123,
      "MessageStatus": 0
    }]
}

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.

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