MaxMD Direct Message RESTful API v3.0

RESTful Service for sending and retrieving Direct messages, managing Direct mailbox . This page includes description about service actions and data types.

Functions

Send

HTTP PUT Request

https://api.directmdemail.com/message-rest/api/message/Send

Headers

Content-Type: application/json

Request Body

JSON Object: SendRequest

Response

JSON Object: SendMessageResponseType

Description

Send a Direct message. The message will be saved into INBOX.Sent folder as an unread message automatically.

SendWithHeader

HTTP PUT Request

https://api.directmdemail.com/message-rest/api/message/SendWithHeader

Headers

Content-Type: application/json

Request Body

JSON Object: SendRequestWithHeader

Response

JSON Object: SendMessageResponseType

Description

Send a Direct message with customized headers. The message will be saved into INBOX.Sent folder as an unread message automatically.

ForwardMessagesByUIDs

HTTP PUT Request

https://api.directmdemail.com/message-rest/api/message/Forward/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: UidsRequestType

Response

JSON Object: SendMessageResponseType

Description

Forward messages by folder name and uids. If multiple messages (multiple uid) are selected, the messages will be forwarded as attachments. The message will be saved into INBOX.Sent folder as an unread message.

GetMessageStatus

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessageStatus/{smtpId}

Request Body

JSON Object: Authentication

Response

JSON Object: DirectMessageStatusReportResponseType

Description

Get the message information.
Each recipient of the a Direct message has it's own record. It may return multiple MessageLog records if the Direct message has multiple recipients.

GetMessagesStatusBySmtpIds

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessageStatus/

Headers

Content-Type: application/json

Request Body

JSON Object: SmtpIdsRequestType

Response

JSON Object: DirectMessageStatusReportResponseType

Description

Get information of multiple messages.

GetMessageCount

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessageCount/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetCountResponse

Description

Get the number of messages in a folder

GetUnreadMessageCount

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetUnreadMessageCount/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetCountResponse

Description

Get the number of unread messages in a folder

GetDeletedMessageCount

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetDeletedMessageCount/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetCountResponse

Description

Get the number of deleted messages in a folder

GetMessagesByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessagesByUIDs/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: UidsRequestType

Response

JSON Object: GetMessageResponse

Description

Get messages from a specified folder by UIDs.

GetUnreadMessages

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetUnreadMessages/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get all unread messages from a specified folder

GetMessagesByReceivedDate

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessagesByReceivedDate/{folderName}/{beginTime}/{endTime}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get messages filtered by the received date
beginTime is Unix Time stamp: milliseconds since the Unix Epoch (1970-01-01T00:00:00Z ISO-8601) endTime is Unix Time stamp: milliseconds since the Unix Epoch (1970-01-01T00:00:00Z ISO-8601)

GetMessagesByReceivedDateUTC

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessagesByReceivedDateUTC/{folderName}/{beginTime}/{endTime}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get messages filtered by the received date
beginTime and endTime in UTC. Format: yyyyMMddHHmmss, ex: 20160705174715 == Jul 05,2016 17:47:15 UTC or 13:47:15 EDT.

GetMessagesBySender

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessagesBySender/{folderName}/{sender}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get messages filtered by sender

GetMessagesBySubject

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessagesBySubject/{folderName}/{subject}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get messages filtered by subject

GetMessages

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessages/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get all messages from specific folder

GetMessageMetaData

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetMessageMetaData/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get all metadata in the folder

SearchMessagesMetadataByReceivedDate

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/SearchMessagesMetadataByReceivedDate/{folderName}/{beginTime}/{endTime}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get all metadata in the folder that filtered by the received date
beginTime is Unix Time stamp: milliseconds since the Unix Epoch (1970-01-01T00:00:00Z ISO-8601) endTime is Unix Time stamp: milliseconds since the Unix Epoch (1970-01-01T00:00:00Z ISO-8601)

SearchMessagesMetadataByReceivedDateUTC

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/SearchMessagesMetadataByReceivedDateUTC/{folderName}/{beginTime}/{endTime}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetMessageResponse

Description

Get all metadata in the folder that filtered by the received date
beginTime and endTime in UTC. Format: yyyyMMddHHmmss, ex: 20160705174715 == Jul 05,2016 17:47:15 UTC or 13:47:15 EDT.

GetUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetUIDs/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetUIDResponseType

Description

Get all UIDs in a specified folder. This function is useful to synchronize the folder's messages with server

GetFolders

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetFolders/{rootFolderName}/{subscribedFolderOnly}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: GetFoldersResponseType

Description

Get sub-folders of a spedified folder.

SetFoldersSubscribed

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/SetFoldersSubscribed/

Headers

Content-Type: application/json

Request Body

JSON Object: SetFoldersSubscribedRequestType

Response

JSON Object: GetFoldersResponseType

Description

Set a list of folders to subscribed/unsubscribed

CreateFolder

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/CreateFolder/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: APIResponse

Description

Create a new folder. All folder names should start with "INBOX.". And below reserved folders can not be re-created or deleted:

  • INBOX
  • INBOX.Sent
  • INBOX.Templates
  • INBOX.Drafts
  • INBOX.Spam

MoveFolder

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/MoveFolder/{folderName}/{newFolderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: APIResponse

Description

Rename a un-reserved folder

DeleteFolder

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/DeleteFolder/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: Authentication

Response

JSON Object: APIResponse

Description

Recursively delete a un-reserved folder. All inside messages and sub-folders will be deleted also.

CopyMessagesByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/CopyMessagesByUIDs/{folderName}/{destFolderName}

Headers

Content-Type: application/json

Request Body

JSON Object: UidsRequestType

Response

JSON Object: APIResponse

Description

Copy messages by UIDs

MoveMessagesByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/MoveMessagesByUIDs/{folderName}/{destFolderName}

Headers

Content-Type: application/json

Request Body

JSON Object: UidsRequestType

Response

JSON Object: APIResponse

Description

Move messages by UIDs

DeleteMessagesByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/DeleteMessagesByUIDs/{folderName}/{deleteForever}

Headers

Content-Type: application/json

Request Body

JSON Object: UidsRequestType

Response

JSON Object: APIResponse

Description

Delete messages by UIDs. If deleteForever is false, the messages will be moved to INBOX.Trash folder

MarkMessagesAsReadByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/MarkMessagesAsReadByUIDs/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: UidsRequestType

Response

JSON Object: APIResponse

Description

Mark messages as READ by UIDs

MarkMessagesAsUnreadByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/MarkMessagesAsUnreadByUIDs/{folderName}

Headers

Content-Type: application/json

Response

JSON Object: APIResponse

Description

Mark messages as UNREAD by UIDs

GetRawMessagesByUIDs

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/GetRawMessagesByUIDs/{folderName}

Headers

Content-Type: application/json

Response

JSON Object: GetRawMessageResponse

Description

Get messages raw data by a list of Unique ID. The Unique ID is the received order of a message. It is unchangeable and unique in a folder. It is recommended to use UniqueID to identity each message.

SaveRawMessages

HTTP POST Request

https://api.directmdemail.com/message-rest/api/message/SaveRawMessages/{folderName}

Headers

Content-Type: application/json

Request Body

JSON Object: RawMessagesRequestType

Response

JSON Object: APIResponse

Description

Get messages raw data by a list of Unique ID. The Unique ID is the received order of a message. It is unchangeable and unique in a folder. It is recommended to use UniqueID to identity each message.

Data types

SendRequest

Parameter Description
Authentication authentication Authentication information Required
Message message Message data Required
Top

SendRequestWithHeader

Parameter Description
Authentication authentication Authentication information Required
MessageWithHeader message Message data with customized headers Required
Top

Authentication

Parameter Description
String username Direct email address Required
String password User password Required
Top

UidsRequestType

Parameter Description
Authentication auth Authentication information Required
long[] uids Array of UIDs Required
RecipientCollection recipients Collection of all recipients Optional
Top

SmtpIdsRequestType

Parameter Description
Authentication auth Authentication information Required
String[] smtpIds Array of SMTP IDs Required
Top

SetFoldersSubscribedRequestType

Parameter Description
Authentication auth Authentication information Required
String[] folders Array of folder name Required
boolean subscribed True: set folder subscribed
False: set folder unsubscribed		 Required
Top

RawMessagesRequestType

Parameter Description
Authentication auth Authentication information Required
RawMessage[] messages Array of raw message Required
Top

Message

Parameter Description
String sender From email address (same as username) Required
String subject Email subject
String body Email body
boolean htmlBody true: html body, false: plain text body Required
Recipient[] recipients An array of recipient objects Required
Attachment[] attachmentList An array of attachment objects
Top

MessageWithHeader

Parameter Description
String sender From email address (same as username) Required
String subject Email subject
String body Email body
boolean htmlBody true: html body, false: plain text body Required
Recipient[] recipients An array of recipient objects Required
Attachment[] attachmentList An array of attachment objects
MessageHeader[] headers An array of message headers
Top

Recipient

Parameter Description
String email Recipient's email address Required
RecipientType type Recipient type (TO|CC|BCC) Required
Top

FHIRResourceType

Parameter Description
String resourceType Resource Type Read the Spec Required
FHIRQueryParameterType[ ] queryParameters Query parameters
Top

FHIRQueryParameterType

Parameter Description
String name Parameter name Required
String name Parameter value Required
Top

Attachment

Parameter Description
String content Base64 encoded data of the attachment Required
String contentType Content-Type of the attachment Required
String filename Attachment file name Required
Top

APIResponse

Parameter Description
boolean success whether action is successful
int code Error code (1: authentication failed, 2: address error, 3 and 4: other error
String message Information of the SOAP request
Top

SendMessageResponseType ( extends APIResponse )

Parameter Description
String smtpId The Message-ID of the Direct message you just sent or forwarded. You will use this id to check the message status.
Top

DirectMessageStatusReportResponseType ( extends APIResponse )

Parameter Description
boolean hasCvData true: csvData is responsed, messageLogs is empty
false: messageLogs is responsed, csvData is empty
byte[] csvData csv formatted message status report data with below columns:
  1. From Sender direct address
  2. To Recipient direct address
  3. Message ID SMTP Message ID of the message
  4. Message Size Size of the message
  5. Status Status of the message
    • Delivered* Delivered to receiver
    • Waiting* Waiting confirmation from receiver HISP
    • Locally Failed* Rejected or failed when sending it out.
    • Remotely Failed* Rejected or failed by receiver HISP
    • NO MDN Received* Timed out. No confirmation received from receiver HISP within one hour
  6. Sent Time Sent time of the message
  7. XDR Message ID XDR Message ID
  8. XDR Source ID XDR Source ID
  9. XDR Unique ID XDR Unique ID
  10. XDR Patient ID XDR Patient ID

This variable is empty if hasCvData==false or no message was found in the certain date range.
DirectMessageLog[] messageLogs And list of message log object. This variable is empty if hasCvData==true or no message was found in the certain date range.
Top

DirectMessageLog

Parameter Description
String from Sender direct address of the message
String to Recipient direct address of the message
String messageId SMTP Message ID of the message
long messageSize size of the message
String status Status of the message:
  • Delivered Delivered to receiver
  • Waiting Waiting confirmation from receiver HISP
  • Locally Failed Rejected or failed when sending it out.
  • Remotely Failed Rejected or failed by receiver HISP
  • NO MDN Received Timed out. No confirmation received from receiver HISP within one hour
String statusDetails Details of delivery status
Date ts Sent time
String xdrId XDR Message ID
String uniqueId XDR Unique ID
String sourceId XDR Source ID
String patientId XDR Patient ID
Top

GetFoldersResponseType ( extends APIResponse )

Parameter Description
String[] folders The folders
Top

GetCountResponse ( extends APIResponse )

Parameter Description
int count The count number
Top

GetMessageResponse (extends APIResponse )

Parameter Description
MessageDetail[] messages An array of searched messages
Top

MessageDetail ( extends Message )

Parameter Description
longuid New parameter. The received order in a folder. Is uid is unique and will not be changed in a folder.
int msgnum The message number for this message
String msgID Message ID of this message.
This method returns null if the corresponding header is not present.
String folder Get the folder from which this message was obtained.
If this is a new message or nested message, this method returns null.
boolean expunged Whether the message is expunged
String sender From email address (same as username) (Inherited from APIResponse )
int size The size of the content of this message in bytes.
Return -1 if the size cannot be determined.
Date sentDate The Date the message was sent
Date receivedDate The Date the message was received
String replyTo Get the addresses to which replies should be directed.
This will usually be the sender of the message, but
some messages may direct replies to a different address.
This method returns null if the corresponding header is not present.
MessageHeader[] headers An array of message header objects
String subject Email subject (Inherited from APIResponse )
String body Email body (Inherited from APIResponse )
boolean htmlBody true: html body, false: plain text body (Inherited from APIResponse )
Recipient[] recipients An array of recipient objects (Inherited from APIResponse )
Attachment[] attachments An array of attachment objects (Inherited from APIResponse )
Top

MessageHeader

Parameter Description
String name Name of this header line
String value Value of this header line
Top

GetUIDResponseType ( extends APIResponse )

Parameter Description
long[] uids List of UIDs
Top

GetRawMessageResponse (extends APIResponse )

Parameter Description
RawMessage[] messages An array of searched messages
Top

RawMessage

Parameter Description
longuid New parameter. The received order in a folder. Is uid is unique and will not be changed in a folder.
String msgID Message ID of this message.
This method returns null if the corresponding header is not present.
String folder Get the folder from which this message was obtained.
If this is a new message or nested message, this method returns null.
String data Base64 encoded message raw data.
Top