Skip to content

Latest commit

 

History

History
373 lines (258 loc) · 10.4 KB

api.md

File metadata and controls

373 lines (258 loc) · 10.4 KB
Raw

API

The current API uses AWS API Gateway, which invokes Lambda functions in api/*.

Endpoint

Dev Endpoint: https://{api_id}.execute-api.{region}.amazonaws.com/

The default endpoint is generated by API Gateway. It can be found from your AWS console -> APIs -> <your-api-name> -> Settings -> Default Endpoint.

Methods

List

Lists emails based on query parameters.

GET /emails

Query String Parameters:

  • type: inbox or draft or sent
  • year: four digit year (default to current year)
  • month: one or two digit month (default to current month)
    • e.g. for March, both 3 and 03 are supported
  • order: asc or desc (default)
  • showTrash: exclude (default), include, or only
  • pageSize: the max size of a single page
  • nextCursor: cursor returned by List response (optional)

Note:

  • although year and month are optional, they must be both provided or both left empty.
  • when specifying pageSize, it's possible to have less items, but there's still a next page

Response:

Field Type Description
count number Number of emails returned
items object array Email items
    [*].messageID string ID of created draft email
    [*].type string inbox, draft or sent
    [*].subject string Email subject
    [*].from string array From addresses
    [*].to string array To addresses
    [*].timeReceived RFC3339 string Received time (only for inbox emails)
    [*].timeUpdated RFC3339 string Last updated time (only for draft emails)
    [*].timeSent RFC3339 string Sent time (only for sent emails)
nextCursor string Cursor used to get next page
hasMore boolean If there're more emails

Error Response:

Status Code Error Message
400 Bad Request invalid input
429 Too Many Requests too many requests

Get

Get an email given it's messageID.

GET /emails/{messageID}

Path Parameters:

  • messageID: ID of the email message

Response:

Field Type Description
messageID string ID of the email
type string inbox, draft or sent
subject string Subject of email
from string array From addresses
to string array To addresses
text string Email content in text
html string Email content in HTML
timeReceived RFC3339 string Received time (only for inbox emails)
dateSent RFC3339 string The date field in email MIME (only for inbox emails)
source string Source email (only for inbox emails)
destination string array Destination emails (only for inbox emails)
returnPath string Email return path (only for inbox emails)
verdict object Verdict information provided by SES (only for inbox emails)
    spam boolean If spam check passes
    dkim boolean If DKIM check passes
    dmarc boolean If DMARC check passes
    SPF boolean If spf check passes
    virus boolean If virus check passes
timeUpdated RFC3339 string Last updated time (only for draft emails)
cc string array Cc addresses (only for draft and sent emails)
bcc string array Bcc addresses (only for draft and sent emails)
replyTo string array ReplyTo addresses (only for draft and sent emails)
attachments File object array Attachments
inlines File object array Inline files
otherParts File object array Other parts that is not an attachment or inline

Error Response:

Status Code Error Message
404 Not Found email not found
429 Too Many Requests too many requests

Get Raw

Get a raw MIME email given it's messageID.

GET /emails/{messageID}/raw

Path Parameters:

  • messageID: ID of the email message

Response:

Raw email in MIME format

Error Response:

Status Code Error Message
404 Not Found email not found
429 Too Many Requests too many requests

Read

Mark an email as read given it's messageID.

POST /emails/{messageID}/read

Path Parameters:

  • messageID: ID of the email message

Response:

Field Type Description
status string always success

Error Response:

Status Code Error Message
400 Bad Request invalid action
429 Too Many Requests too many requests

Unread

Mark an email as unread given it's messageID.

POST /emails/{messageID}/read

Path Parameters:

  • messageID: ID of the email message

Response:

Field Type Description
status string always success

Error Response:

Status Code Error Message
400 Bad Request invalid action
429 Too Many Requests too many requests

Trash

Trash an untrashed email given it's messageID.

POST /emails/{messageID}/trash

Path Parameters:

  • messageID: ID of the email message

Note: if the email is already trashed, 400 Bad Request will be returned. If the email is a draft, trash method is not supported.

Response:

Field Type Description
status string always success

Error Response:

Status Code Error Message
400 Bad Request email is already trashed
429 Too Many Requests too many requests

Untrash

Untrash an trashed email given it's messageID.

POST /emails/{messageID}/untrash

Path Parameters:

  • messageID: ID of the email message

Note: if the email is not trashed, 400 Bad Request will be returned. If the email is a draft, untrash method is not supported.

Response:

Field Type Description
status string always success

Error Response:

Status Code Error Message
400 Bad Request email already not trashed
429 Too Many Requests too many requests

Delete

Permanently delete an trashed email given it's messageID.

DELETE /emails/{messageID}

Path Parameters:

  • messageID: ID of the email message

Note: if the email is not trashed and email type is inbox or sent, 400 Bad Request will be returned.

Response:

Field Type Description
status string always success

Error Response:

Status Code Error Message
400 Bad Request email not trashed
429 Too Many Requests too many requests

Create

Create a draft email.

POST /emails

Request Body (JSON formatted):

Field Type Description
subject string Subject of email
from string array From addresses
to string array To addresses
cc string array Cc addresses
bcc string array Bcc addresses
replyTo string array ReplyTo addresses
text string email content in text
html string email content in HTML
generateText1 string (optional) on, off, or auto (default)
send boolean (optional) send email immediately without creating draft (default false)

Response:

Field Type Description
messageID string ID of created draft email
type string draft or sent
subject string Subject of email
from string array From addresses
to string array To addresses
cc string array Cc addresses
bcc string array Bcc addresses
replyTo string array ReplyTo addresses
text string email content in text
html string email content in HTML

Error Response:

Status Code Error Message
400 Bad Request invalid input
429 Too Many Requests too many requests

Save

Save a draft email, which is identified by messageID returned from 'Create' operation.

Note: this operation replaces the entire draft email, so all fields must be supplied to it will be removed.

PUT /emails/{messageID}

Path Parameters:

  • messageID: ID of the email message

Request Body (JSON formatted):

Field Type Description
subject string Subject of email
from string array From addresses
to string array To addresses
cc string array Cc addresses
bcc string array Bcc addresses
replyTo string array ReplyTo addresses
text string email content in text
html string email content in HTML
generateText1 string (optional) on, off, or auto (default)
send boolean (optional) send email immediately without creating draft (default false)

Response:

Field Type Description
messageID string ID of saved draft email
type string draft or sent
subject string Subject of email
from string array From addresses
to string array To addresses
cc string array Cc addresses
bcc string array Bcc addresses
replyTo string array ReplyTo addresses
text string email content in text
html string email content in HTML

Error Response:

Status Code Error Message
400 Bad Request invalid input
429 Too Many Requests too many requests

Send

Send a draft email, which is identified by messageID.

POST /emails/{messageID}/send

Path Parameters:

  • messageID: ID of the email message

Error Response:

Status Code Error Message
429 Too Many Requests too many requests

Other object definitions

File

Field Type Description
contentID string Content-ID
contentType string Content-Type
contentTypeParams map A map contains extra parameters in Content-Type
filename string Filename

Footnotes

  1. Field generateText: If on, text is always generated from HTML. If off, text is never generated. If auto (default), text is generated if text is empty. ↩ ↩2