MaxMD Direct Message SOAP API v3.0

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

MTOM is required by the SOAP server. Click here to access the WSDL

Functions

SendMessageResponseType Send (SendRequest sendRequest )

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

SendMessageResponseType SendWithHeader (SendRequestWithHeader sendRequest )

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

SendMessageResponseType ForwardMessagesByUID (Authentication auth, String folderName, long[] uids, Recipient[] recipients )

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.

DirectMessageStatusReportResponseType GetMessageStatus (Authentication auth, String smtpId )

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.

DirectMessageStatusReportResponseType GetMessagesStatusBySmtpIds (Authentication auth, String [] smtpIds )

Get information of multiple messages.

GetFoldersResponseType GetFolders (Authentication auth, String folderName, boolean subscribedFolderOnly )

Get sub-folders of a spedified folder.

APIResponse SetFolderSubscribed (Authentication auth, String[] folderNames, boolean subscribed )

Set a list of folders to subscribed/unsubscribed

GetCountResponse GetMessageCount (Authentication auth, String folderName )

Get the number of messages in a folder

GetCountResponse GetUnreadMessageCount (Authentication auth, String folderName )

Get the number of unread messages in a folder

GetCountResponse GetDeletedMessageCount (Authentication auth, String folderName )

Get the number of deleted messages in a folder

GetCountResGetMessageResponseponse GetMessageByIndex (Authentication auth, String folderName, int index )

Get a message by using the message index. The index will change if some messages were deleted. For example: we have 4 messages in a folder

  1. Message A
  2. Message B
  3. Message C
  4. Message D
If we delete Message B, the indexes will change from 1 2 3 4 to 1 2 3
  1. Message A
  2. Message C
  3. Message D

GetMessageResponse GetMessages (Authentication auth, String folderName )

Get all messages from a specified folder.

GetMessageResponse GetUnreadMessages (Authentication auth, String folderName )

Get all unread messages in a specified folder

GetMessageResponse GetMessagesByIndexes (Authentication auth, String folderName, int[] indexes )

Get messages by using an array of message indexes

GetMessageResponse GetMessagesByReceivedDate (Authentication auth, String folderName, long beginTime, long endTime )

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)

GetMessageResponse GetMessagesByReceivedDateUTC (Authentication auth, String folderName, String beginTime text in UTC, String endTime text in UTC )

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.

GetMessageResponse GetMessagesBySender (Authentication auth, String folderName, String sender )

Get messages filtered by sender

GetMessageResponse GetMessagesBySubject (Authentication auth, String folderName, String subject )

Get messages filtered by subject

GetMessageResponse GetMessagesByUID (Authentication auth, String folderName, long[] uids )

Get messages 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.

APIResponse CreateFolder (Authentication auth, String folderName )

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

APIResponse MoveFolder (Authentication auth, String folderName, String newfolderName )

Rename a un-reserved folder

APIResponse DeleteFolder (Authentication auth, String folderName )

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

APIResponse CopyMessagesByUID (Authentication auth, String folderName, long[] uids, String destFolderName )

Copy messages by UIDs

APIResponse MoveMessagesByUID (Authentication auth, String folderName, long[] uids, String destFolderName )

Move messages by UIDs

APIResponse DeleteMessagesByUID (Authentication auth, String folderName, long[] uids, boolean deleteForever )

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

APIResponse MarkMessagesAsReadByUID (Authentication auth, String folderName, long[] uids )

Mark messages as READ by UIDs

APIResponse MarkMessagesAsUnReadByUID (Authentication auth, String folderName, long[] uids )

Mark messages as UNREAD by UIDs

GetUIDResponseType GetUIDs (Authentication auth, String folderName )

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

GetMessageResponse GetMessageMetadata (Authentication auth, String folderName )

Get all metadata in the folder

GetMessageResponse SearchMessagesMetadataByReceivedDate (Authentication auth, String folderName, long beginTime, long endTime )

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)

GetMessageResponse SearchMessagesMetadataByReceivedDateUTC (Authentication auth, String folderName, String beginTime text in UTC, String endTime text in UTC )

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.

GetRawMessageResponse GetRawMessagesByUID (Authentication auth, String folderName, long[] uids )

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.

APIResponse SaveRawMessages (Authentication auth, String folderName, RawMessage[] messages )

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

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

Attachment

Parameter Description
byte[] content Binary 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.
byte[] data Message raw data.
Top

Message API v2 to V3 updates