Mail API

The Mail API helps you manage settings such as emails, folders (mailboxes), and filters.

To use the Mail API, which deals with sensitive user information, you need an access token that you can get by authenticating with a user account, not a service account. The API scopes are mail and mail.read.

Send, read, and delete messages {#send-get-delete-mail}

Every email message is assigned a unique ID (mailID) and belong to a folder, which is also assigned a unique ID (folderID).

Send a message {#send-mail}

Use the following API operation to send an email message.

HTTP request	Description
POST /users/{userId}/mail	Send a message

The recipient's email address (to) and the message subject must be specified.

{   "to": "admin@example.com",   "subject": "Subject"}

You can also specify cc, bcc, and body.

Attach a file {#add-attachment-file}

To attach a file, specify an object containing the file name (filename), content type (fileType), and Base64-encoded data (data) for the attachment file information (attachments).

{...   "attachments" :   [       {         "filename": "index.html",         "fileType": "text/html",        "data" : "PGh0bWw+CjxoZWFkPgo8dGl0bGU+V2VsY29tZSB0byBXT1JLUyBBUEkhPC90aXRsZT4KPC9oZWFkPgo8Ym9keT4KPGgxPldlbGNvbWUgdG8gV09SS1MgQVBJICE8L2gxPgpUaGlzIGlzIGEgZG9jdW1lbnQgZm9yIFdPUktTIEFQSS4KPC9ib2R5Pgo8L2h0bWw+"       }   ]}

Attach an inline image {#add-inline-picture}

To attach an inline image in the body, add an img tag containing the content ID (cid) using the src property where you want the image to appear.

Example)<img src="cid:reddotiVBORw0KGgoAAAA"alt="Red dot"/>

Set inline to true, and specify an object containing cid, filename, fileType, and Base64-encoded file data for attachments.

{    "attachments": [        {            "cid": "reddotiVBORw0KGgoAAAA",            "fileType": "image/png",            "inline" : true,            "filename": "red_dot.png",            "data": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="        }    ],    "body": "<html><body>red dot is here:<img src=\"cid:reddotiVBORw0KGgoAAAA\"></body></html>",...

Read a message {#get-mail}

Get folders {#get-mail-folder-list}

To read an email message, call the API operations in the following order:
First, get folders to obtain the folder ID (folderId), folder name (folderName), the number of unread messages (unreadMailCount), and the total number of messages (mailCount).

HTTP request	Description
GET /users/{userId}/mail/mailfolders	Get folders

{     "mailFolders": [         {             "folderId": 0,             "folderType": "S",             "folderName": "Inbox",             "unreadMailCount": 12,             "mailCount": 14,             "usage": 285117,             "folderDepth": 0,             "parentFolderId": 0,             "hasChildFolder": false         },...

With the folderId, you can get the messages of a specific folder to obtain the email summary information including the sender's email address (from), the recipient's email address (to), the message status (status: read/unread), the received time (receivedTime), the total number of messages in the folder (totalCount), and the number of unread messages (unreadCount).

Get messages in a specific folder {#get-mail-folder-mail-list}

HTTP request	Description
GET /users/{userId}/mail/mailfolders	Get messages in a specific folder

{     "mails": [         {             "mailId": 1234,             "folderId": 0,             "status": "Unread",             "from": {                 "name": "Sender",                 "email": "sender@example.com"             },             "to": [                 {                     "name": "Recipient",                     "email": "reciever@exapmle.com"                 }             ],             "subject": "Subject",             "receivedTime": "2023-05-12T11:25:38+09:00",             "sentTime": "2023-05-12T11:25:38+09:00",             "size": 19948,             "attachCount": 1,...         },...     ],     "unreadCount": 12,     "folderName": "Inbox",     "totalCount": 123,     "responseMetaData": {         "nextCursor": "eyJuZXh0Q3Vyc29yIjoiMyIsInBhZ2VTaXplIjoiMiIsInR5cGUiOiJhbGwiLCJpc1VucmVhZCI6ImZhbHNlIn0="     },     "listCount": 30}

Read a message {#get-mail}

To get the details of a message, such as message content (body), use the following API operation with the mailId specified.

HTTP request	Description
GET /users/{userId}/mail/{mailId}	Read a message

{     "attachments": [],     "mail": {         "mailId": 1234,         "folderId": 1,         "status": 260,         "from": {                 "name": "Sender",                 "email": "sender@example.com"         },         "to": [             {                 "name": "Recipient",                 "email": "reciever@exapmle.com"             }         ],         "subject": "Subject",         "body": "Body",         "receivedTime": "2023-05-12T11:25:38+09:00",         "sentTime": "2023-05-12T11:25:38+09:00",         "size": 608,...     }}

Download an attachment {#download-attachment}

If you read a message that has an attachment, the attachment information (attachments) is returned as a response.
The attachment may have a limited retention period.

Attachment type	attachmentId	bigFileFid	How to download
Attachment with no limited retention period	Integer	-	Specify an attachmentID to download the file.
Attachment with a limited retention period	-1	Any value	Specify a BigFileFid to download the file.
Inline image	-2	-	Use data to display an inline image.

Attachment with no limited retention period {#normal-attachment}

Here is an example of attachments with no limited retention periodn.

{    "attachments": [        {            "attachmentId": 2,            "contentType": "",            "charset": null,            "filename": "image.png",            "encoding": null,            "size": 42445,            "bigFileExpireTime": "",            "bigFileFid": ""        }    ],...

The attachmentID for an attachment with no limited retention period is a positive number.
You can download the attachment of a message using the Base64-encoded data, which you can get using the following API operation with the mailId and attachmentId specified.

HTTP request	Description
GET /users/{userId}/mail/{mailId}/attachments/{attachmentId}	Download an attachment

Attachment with a limited retention period {#attachment-with-expiration-date}

The attachments with a limited retention period is returned in the following format, including the retention period (bigFileExpireTime) and the file ID (bigFileFid).

{    "attachments": [        {            "attachmentId": -1,            "contentType": "",            "charset": null,            "filename": "image.png",            "encoding": null,            "size": 42445,            "bigFileExpireTime": "2023-05-31T23:59:59+09:00",            "bigFileFid": "vZKZKAgmKxu9KouwFog9FmK3YrM6EqFqKmKoFMxFopAKwpAMwpg==&rl=12345"        }    ],...

The attachmentId of an attachment with a limited retention period is -1.
You can use the file ID (bigFileFid) to download the attachment, as in the https://bigfile.mail.worksmobile.com/download?fid={bigFileFid} format.

https://bigfile.mail.worksmobile.com/download?fid=vZKZKAgmKxu9KouwFog9FmK3YrM6EqFqKmKoFMxFopAKwpAMwpg%3D%3D%26rl%3D12345

Inline image {#inline-image}

The attachments of an inline image is returned in the following format, where the attachmentId is -2, contentDisposition is inline, and the data contains Base64-encoded image data.

{    "attachments": [        {            "attachmentId": -2,            "cid": "reddotiVBORw0KGgoAAAA",            "contentType": "image/png",            "contentDisposition": "inline",            "charset": "shift-jis",            "filename": "red_dot.png",            "encoding": "base64",            "size": 85,            "data": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="        }    ],    "mail": {        "body": "<html><body>Red dot is here<img src=\"cid:reddotiVBORw0KGgoAAAA\"></body></html>",...    }

You can convert an inline image to a data URL including contentType, encoding, and data, by referencing a cid that corresponds to the attachments.
The data URL schema is as follows: src="data: {contentType}; {encoding}, {data}"

Example:

Before conversion: <img src="cid:reddotiVBORw0KGgoAAAA" alt="Red dot">
After conversion: <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" alt="Red dot"/>

For more information, see RFC 2387 The MIME Multipart/Related Content-type.

Delete a message {#delete-mail}

To delete a message, use the following API operation with the mailID specified.

HTTP request	Description
DELETE /users/{userId}/mail/{mailId}	Delete a message

Manage messages {#manage-mail}

You can get the number of unread messages in all folders and mark messages as Read or Important.

HTTP request	Description
GET /users/{userId}/mail/unread-count	Get the number of unread messages
PATCH /users/{userId}/mail/{mailId}	Mark a message as Important or Read

Manage folders and filters {#manage-folder-filter}

You can manage folders and filters using the following API operations.

Manage folders {#manage-folder}

Folders are used to categorize email messages. You can add, update, and delete folders using the the following API operations.

HTTP request	Description
POST /users/{userId}/mail/mailfolders	Add a folder
PUT /users/{userId}/mail/mailfolders/{folderId}	Rename a folder
DELETE /users/{userId}/mail/mailfolders/{folderId}	Delete a folder

Folders are subdivided into two types: system folders and custom folders.
Whereas system folders are provided by the system and thus cannot be updated or deleted, custom folders can be updated or deleted as needed.

Manage filters {#manage-filter}

Filters help you automatically filter messages, highlight certain messages, and forward them to a specified email address.

HTTP request	Description
POST /users/{userId}/mail/filters	Add a filter
GET /users/{userId}/mail/filters	Get filters
GET /users/{userId}/mail/filters/{filterId}	Get a filter
DELETE /users/{userId}/mail/filters/{filterId}	Delete a filter