Mail API로 메일, 메일함, 자동 분류 등의 설정을 관리할 수 있다.
Mail은 민감한 사용자 정보이므로 구성원 계정으로 인증하여 얻은 Access Token으로만 사용할 수 있다. 서비스 계정으로 인증하여 얻은 Access Token으로는 사용할 수 없다. API scope는 mail, mail.read이다.
모든 메일에는 고유 ID인 메일 ID(mailId)가 할당된다.
모든 메일은 메일함에 포함되어 메일함에도 고유 ID인 folderId가 할당된다.
메일을 보내려면 다음 API를 사용한다.
| HTTP Request | Description |
|---|---|
| POST /users/{userId}/mail | 메일 발송 |
메일의 받는 사람 메일 주소(to)와 제목(subject)은 반드시 지정해야 한다.
{ "to": "admin@example.com", "subject": "제목"}참조와 숨은 참조 메일 주소(cc/bcc)와 메일 내용(body)을 지정할 수 있다.
파일을 첨부하는 경우 파일명(filename), 파일의 contentType(fileType), Base64로 인코딩된 파일의 데이터(data)가 포함된 객체를 첨부 파일 정보(attachments)로 지정한다.
{... "attachments" : [ { "filename": "index.html", "fileType": "text/html", "data" : "PGh0bWw+CjxoZWFkPgo8dGl0bGU+V2VsY29tZSB0byBXT1JLUyBBUEkhPC90aXRsZT4KPC9oZWFkPgo8Ym9keT4KPGgxPldlbGNvbWUgdG8gV09SS1MgQVBJICE8L2gxPgpUaGlzIGlzIGEgZG9jdW1lbnQgZm9yIFdPUktTIEFQSS4KPC9ib2R5Pgo8L2h0bWw+" } ]}본문에 인라인 이미지를 첨부하는 경우, 이미지를 삽입하려는 위치에 src 속성으로 콘텐츠 식별값인 cid를 포함하는 img 태그를 추가한다.
<img src="cid:reddotiVBORw0KGgoAAAA"alt="Red dot"/>inline이 true이고, 콘텐츠 식별값(cid), 파일명(filename), 파일의 contentType(fileType), Base64로 인코딩된 파일의 데이터(data)가 포함된 객체를 첨부 파일 정보(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>",...메일을 보려면 다음 순서로 API를 호출한다.
우선 메일함 목록을 조회하여 메일함 ID(folderId), 메일함 이름(folderName), 안 읽은 메일 개수(unreadMailCount), 총 메일 개수(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 },...위에서 얻은 folderId로 특정 메일함의 메일 목록 조회 시 보낸 사람의 메일 정보(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}메일 내용(body) 등의 메일 상세 정보는 메일 ID(mailId)를 지정해 다음 API를 호출하면 얻을 수 있다.
| 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,... }}메일 읽기 API 호출 시 메일에 파일이 첨부되어 있으면 첨부 파일 정보(attachments)가 응답으로 반환된다.
첨부 파일에 다운로드 기한이 있을 수 있다.
| 첨부 파일 유형 | attachmentId | bigFileFid | 다운로드 방법 |
|---|---|---|---|
| 다운로드 기한이 없는 첨부 파일 | 정수 | - | attachmentId를 지정하여 다운로드 |
| 다운로드 기한이 있는 첨부 파일 | -1 | 값이 있다 | bigFileFid를 지정하여 다운로드 |
| 인라인 이미지 | -2 | - | data를 이용하고 인라인 영상으로 표시 |
다음은 다운로드 기한이 없는 첨부 파일 정보(attachments)의 기본 형식 예시이다.
{ "attachments": [ { "attachmentId": 2, "contentType": "", "charset": null, "filename": "이미지.png", "encoding": null, "size": 42445, "bigFileExpireTime": "", "bigFileFid": "" } ],...다운로드 기한이 없는 첨부 파일의 attachmentId는 양수다.
메일의 첨부 파일은 메일 ID(mailId)와 첨부 파일 ID(attachmentId)를 지정해 다음 API를 호출하면 얻을 수 있는, Base64로 인코딩된 첨부 파일 데이터(data)로 다운로드할 수 있다.
| HTTP Request | Description |
|---|---|
| GET /users/{userId}/mail/{mailId}/attachments/{attachmentId} | 첨부 파일 다운로드 |
다운로드 기한이 있는 첨부 파일 정보(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인라인 이미지의 첨부 파일 정보(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를 참고한다.
메일을 삭제하려면 메일 ID(mailId)를 지정해 다음 API를 호출한다.
| HTTP Request | Description |
|---|---|
| DELETE /users/{userId}/mail/{mailId} | 메일 삭제 |
모든 메일함의 안 읽은 메일 개수 조회, 읽음 및 중요 표시를 할 수 있다.
| HTTP Request | Description |
|---|---|
| GET /users/{userId}/mail/unread-count | 안 읽은 메일 개수 조회 |
| PATCH /users/{userId}/mail/{mailId} | 중요 메일 표시/메일 읽음 표시 |
다음 API로 메일함과 메일 자동 분류 기능을 관리할 수 있다.
메일함은 메일을 분류하기 위해 사용된다. 다음 API로 메일함을 추가하거나 수정, 삭제할 수 있다.
| HTTP Request | Description |
|---|---|
| POST /users/{userId}/mail/mailfolders | 메일함 추가 |
| PUT /users/{userId}/mail/mailfolders/{folderId} | 메일함 이름 변경 |
| DELETE /users/{userId}/mail/mailfolders/{folderId} | 메일함 삭제 |
메일함 타입은 시스템 메일함과 사용자가 생성한 메일함으로 나뉜다.시스템 메일함은 시스템에서 제공하는 메일함으로서 수정하거나 삭제할 수 없지만, 사용자가 생성한 메일함은 사용자가 직접 수정하거나 삭제할 수 있다.
메일 자동 분류 기능을 이용하면 수신한 메일의 자동 분류, 강조 표시, 지정한 주소로 메일 전송이 가능하다.
| 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} | 메일 자동 분류 삭제 |