About Communicate Webmail

Communicate Webmail is an accessible, secure web interface that allows users to interact with other Direct messaging users without deploying integration or physical infrastructure. Users can access their Direct messages from any device with internet access. Communicate Webmail encrypts and decrypts the data.

Communicate Webmail provides a REST messaging API. Users can send and receive messages securely over the Direct network using this API.

API Version

The current frozen version of the Communicate Webmail API is 3.5. The API interfaces are stable and guaranteed to stay as such until this version is retired.

The Communicate Webmail API is versioned through the Accept and Content-Type headers, which specify the version of the object to retrieve. For example, version 3.5 of the API is retrieved by requesting the application/vnd.orchestral.Webmail.3_5+json media type. In all cases, application/json is treated as the latest version of the API.

Structure of the REST URIs

The URIs for the Communicate Webmail REST API have the following structure: https://{environment}/actor/current/webmail/DIRECT/mailboxes/resource

For example, https://{environment}/actor/current/webmail/DIRECT/mailboxes/{mailboxAddress}/preferences

API Cheat Sheet

Our cheat sheet uses the following conventions:

  • HTTP verb /Resource URI
    • property

Retrieve Messages from a Folder

Retrieve a Message

Send, Reply or Forward a Message

Send, Reply or Forward a Message with an Attachment

  1. POST /{mailboxAddress}/attachment/{attachmentGroupId}
  2. POST /{mailboxAddress}/outbox

Automatically Forward Messages

Turn on Automatic Replies

Authorize Another Person to access Your Mailbox

Add a Contact

To associate the contact with a contact group, you require the unique identifier of the contact group. (contactGroupId).

Update a Contact

Add a Contact Group

To add a contact to the contact group, you require the unique identifier of the contact (contactId).

Update a Contract Group

Response Codes

The Communicate Webmail API returns standard HTTP response codes.

Code Status Description
200 OK Your request was successfully received, understood and accepted.
201 Created Your request has resulted in a new resource being created.
204 No content Your request was successfully processed, and there is no additional content to send in the body of the response.
400 Bad request Your request was invalid. A parameter, or the data in a parameter, may be incorrect.
401 Unauthorized Your API key or access token has expired or is invalid.
404 Not found The requested resource cannot be found. Please ensure that this resource exists.
409 Conflict Your request cannot be completed due to a conflict with another rule.
413 Payload too large Your request payload is larger than the server is willing or able to process.