Mail API

Mail API では、メールの送信・閲覧・削除や、メールフォルダ・フィルタなどの設定管理が行なえます。
Mail API は、アドバンストプランでのみ利用できます。
また、Mail API では重要なユーザー情報を取り扱うため、User Account 認証で発行された Access Token でのみ呼び出すことができます。Service Account 認証 (JWT) で発行された Access Token では呼び出すことができません。

Scopes: mail, mail.read

メールの送信・閲覧・削除 {#send-get-delete-mail}

すべてのメールには、一意の ID であるメール ID mailId が割り当てられています。
すべてのメールは、いずれかのフォルダに含まれており、フォルダにも一意の ID folderId が割り当てられています。

メールの送信 {#send-mail}

メールを送信するには以下の API を使用します。

HTTP Request	Description
POST /users/{userId}/mail	メールの送信

メールの To メールアドレス to と件名 subject は必ず指定する必要があります。

{  "to": "admin@example.com",  "subject": "タイトル"}

Cc/Bcc メールアドレス cc/bcc や本文 body を指定することもできます。

ファイルの添付 {#add-attachment-file}

ファイルを添付する場合には、ファイル名 filename、ファイル contentType fileType、Base64 エンコードしたファイルのデータ data を指定したオブジェクトを、添付ファイル情報 attachments に指定します。

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

インライン画像の添付 {#add-inline-picture}

インライン画像付きのメールを送信するには、メール本文 body 内のインライン画像を挿入する位置に、src 属性として一意の値を cid の値を持つ img 要素を追加します。
例 : <img src="cid:reddotiVBORw0KGgoAAAA" alt="Red dot"/>

cid に上で指定した一意の値、data に画像データを base64 エンコードした文字列、fileType に contentType、inline に true を指定したオブジェクトを 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>",...

メールの閲覧 {#get-mail}

メールを閲覧するには、以下の順番で API を呼び出します。

メールフォルダリストの取得
メールフォルダ内のメールリストの取得
メールの取得
添付ファイルのダウンロード

メールフォルダリストの取得 {#get-mail-folder-list}

まず、フォルダのリストを取得ます。メールフォルダ ID folderId、フォルダ名 folderName、未読メール数 unreadMailCount、mailCount mailCount などが取得できます。

HTTP Request	Description
GET /users/{userId}/mail/mailfolders	メールフォルダリストの取得

{    "mailFolders": [        {            "folderId": 0,            "folderType": "S",            "folderName": "受信トレイ",            "unreadMailCount": 12,            "mailCount": 14,            "usage": 285117,            "folderDepth": 0,            "parentFolderId": 0,            "hasChildFolder": false        },...

メールフォルダ内のメールリストの取得 {#get-mail-folder-mail-list}

フォルダを指定してフォルダ内のメールリストを取得することで、送信者のメールアドレス from、宛先 to、件名 status、受信時刻 receivedTime などのメールの概要と、フォルダ内のメール総数 totalCount、未読メール数 unreadCount などが取得できます。

HTTP Request	Description
GET /users/{userId}/mail/mailfolders	メールフォルダ内のメールリストの取得

{    "mails": [        {            "mailId": 1234,            "folderId": 0,            "status": "Unread",            "from": {                "name": "メール送信者",                "email": "sender@example.com"            },            "to": [                {                    "name": "メール受信者",                    "email": "reciever@exapmle.com"                }            ],            "subject": "メールタイトル",            "receivedTime": "2023-05-12T11:25:38+09:00",            "sentTime": "2023-05-12T11:25:38+09:00",            "size": 19948,            "attachCount": 1,...        },...    ],    "unreadCount": 12,    "folderName": "受信トレイ",    "totalCount": 123,    "responseMetaData": {        "nextCursor": "eyJuZXh0Q3Vyc29yIjoiMyIsInBhZ2VTaXplIjoiMiIsInR5cGUiOiJhbGwiLCJpc1VucmVhZCI6ImZhbHNlIn0="    },    "listCount": 30}

メールの取得 {#get-mail}

メールの本文 body などメールの詳細は、メール ID mailId を指定してメールを閲覧します。

HTTP Request	Description
GET /users/{userId}/mail/{mailId}	メールの取得

{    "attachments": [],    "mail": {        "mailId": 1234,        "folderId": 1,        "status": 260,        "from": {                "name": "メール送信者",                "email": "sender@example.com"        },        "to": [            {                "name": "メール受信者",                "email": "reciever@exapmle.com"            }        ],        "subject": "メールタイトル",        "body": "メール本文",        "receivedTime": "2023-05-12T11:25:38+09:00",        "sentTime": "2023-05-12T11:25:38+09:00",        "size": 608,...    }}

添付ファイルのダウンロード {#download-attachment}

メールにファイルが添付されている場合には、メールを閲覧した際に、添付ファイル情報 attachments に値が入ります。
メールの添付ファイルには、通常の添付ファイルと、ダウンロード期限が設定されたファイルがあります。

添付ファイルの種類	attachmentId	bigFileFid	取り扱い方法
通常の添付ファイル	正の整数	-	attachmentId を指定してダウンロード
ダウンロード期限が設定された添付ファイル	-1	値あり	bigFileFid を指定してダウンロード
インライン画像	-2	-	data を利用してインライン画像として表示

通常の添付ファイル {#normal-attachment}

通常の添付ファイルに対する添付ファイル情報 attachments は、以下の形式で得られます。

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

通常の添付ファイルは、attachmentId が正の整数です。通常の添付ファイルは、メール ID mailId と添付ファイル ID attachmentId を指定して以下の API を呼び出し、取得した data フィールドを Base64 デコードして取得します。

HTTP Request	Description
GET /users/{userId}/mail/{mailId}/attachments/{attachmentId}	添付ファイルのダウンロード

ダウンロード期限が設定された添付ファイル {#attachment-with-expiration-date}

ダウンロード期限が設定された添付ファイルに対する添付ファイル情報 attachments は以下の形式で返され、ファイルの有効期間 bigFileExpireTime と、ダウンロード期限を設定した場合のファイル ID bigFileFid に値が含まれます。

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

ダウンロード期限が設定された添付ファイルは、attachmentId が -1 です。ダウンロード期限を設定した場合のファイル ID bigFileFid を用い、https://bigfile.mail.worksmobile.com/download?fid={bigFileFid} にアクセスして添付ファイルを取得します。

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

インライン画像 {#inline-image}

インライン画像の添付ファイル情報 attachments は、以下の形式で返されます。
attachmentId は -2、contentDisposition は inline で、画像データを base64 エンコードした情報が 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>",...    }

インライン画像は、添付ファイル情報 attachments より、対応する cid のオブジェクトを参照し、contentType、encoding、data を組み合わせて data URL スキーマに変換することで表示できます。
data URL スキーマは以下の形式になります。
src="data:{contentType};{encoding},{data}"

例 :

置換前 : <img src="cid:reddotiVBORw0KGgoAAAA" alt="Red dot">
置換後 : <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" alt="Red dot"/>

参照 : RFC 2387 The MIME Multipart/Related Content-type

メールの削除 {#delete-mail}

メールの削除は、メール ID mailId を指定して以下の API を呼び出します。

HTTP Request	Description
DELETE /users/{userId}/mail/{mailId}	メールの削除

メールの管理 {#manage-mail}

すべてのメールフォルダにある未読メール数の確認や、メールの未読/既読・重要フラグの切り替えもできます。

HTTP Request	Description
GET /users/{userId}/mail/unread-count	未読メール数の取得
PATCH /users/{userId}/mail/{mailId}	重要メール表示/メール既読表示の切換

メールフォルダ・フィルタなどの設定管理 {#manage-folder-filter}

メールフォルダの管理 {#manage-folder}

メールフォルダは、メールを振り分けるために利用します。以下の API で、メールフォルダの作成・変更・削除ができます。

HTTP Request	Description
POST /users/{userId}/mail/mailfolders	メールフォルダの追加
PUT /users/{userId}/mail/mailfolders/{folderId}	メールフォルダ名の変更
DELETE /users/{userId}/mail/mailfolders/{folderId}	メールフォルダの削除

メールフォルダには、システムにより予め作成されている システムメールフォルダ と、ユーザーが作成した ユーザーメールフォルダ (個人フォルダ) があり、システムメールフォルダ では名前の変更や削除はできません。 ユーザーメールフォルダ (個人フォルダ) は、階層化して構成することも可能です。

フィルタの管理 {#manage-filter}

フィルタ機能により、受信メールの自動振り分けや自動転送、メール一覧画面での強調表示などができます。

HTTP Request	Description
POST /users/{userId}/mail/filters	メールフィルタの登録
GET /users/{userId}/mail/filters	メールフィルタリストの取得
GET /users/{userId}/mail/filters/{filterId}	メールフィルタの取得
DELETE /users/{userId}/mail/filters/{filterId}	メールフィルタの削除