Working with Webmail APIs

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

• GET /{mailboxAddress}/folders/{folderPath}/messages

Retrieve a Message

• GET /{mailboxAddress}/folders/{folderPath}/messages/{messageUid}

Send, Reply or Forward a Message

• POST /{mailboxAddress}/outbox

Send, Reply or Forward a Message with an Attachment

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

Automatically Forward Messages

• POST /{mailboxAddress}/preferences/autoForward or
• PUT /{mailboxAddress}/preferences
  • autoForwardOn
  • autoForwardGroup

Turn on Automatic Replies

• POST /{mailboxAddress}/preferences/autoReply or
• PUT /{mailboxAddress}/preferences
  • autoReplyOn
  • autoReplyMessage

Authorize Another Person to access Your Mailbox

• POST /{mailboxAddress}/preferences/mailboxSharing (if you know the Direct email address of the user you want to share your mailbox with) or
• PUT /{mailboxAddress}/preferences
  • sharedMailboxOn
  • sharedUsers

Add a Contact

• POST /{mailboxAddress}/addressbook/contact

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

Update a Contact

• POST /addressbook/contact/{contactId}

Add a Contact Group

• POST /{mailboxAddress}/addressbook/contactgroup

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

Update a Contract Group

• POST /{mailboxAddress}/addressbook/contactgroup/{contactGroupId}

Response Codes

The Communicate Webmail API returns standard HTTP response codes.