Developers
Open Swarmhit
Smart APIRaw API
API referenceEmail messages
GET
/email/api/v1/emails

Live from the mailbox, newest first. One folder at a time: folder (its provider_id or emf_ id), else role's folder, else All Mail where the mailbox has it (Gmail), else INBOX. Items are 1_meta (no body); include_body=true (ours) fetches the bodies when limit is 25 or less. The filters other than the folder search the folder.

Authorization

X-API-KEY<token>

Your API key from the console (gw_live_…).

In: header

Query Parameters

account_id*string

The mailbox (em_…).

limit?integer

Items per page, 1 to 250. Default 100.

Range1 <= value <= 250
Default100
cursor?string

The previous page's cursor, unchanged; it keeps that page's folder.

folder?string

A folder's provider_id (its path) or emf_ id.

role?string

The folder by its role.

Value in

  • "inbox"
  • "sent"
  • "archive"
  • "drafts"
  • "trash"
  • "spam"
  • "all"
  • "important"
  • "starred"
  • "unknown"
from?string

From this address.

to?string

To, cc or bcc this address.

any_email?string

Comma-separated addresses, sent to or received from.

before?string

Before this date (ISO 8601).

Formatdate-time
after?string

After this date (ISO 8601).

Formatdate-time
thread_id?string
message_id?string

An RFC Message-ID.

search?string

Free text in the subject or the body.

include_body?boolean

Swarmhit's own: 2_full items, bodies included (limit 25 or less).

include_headers?boolean

With include_body, each mail's headers too.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/email/api/v1/emails?account_id=em_gX2kP9qL4mT7vB1nR8sW3yZ"
{  "object": "EmailList",  "items": [    {      "object": "Email",      "id": "string",      "account_id": "string",      "type": "string",      "date": "2019-08-24T14:15:22Z",      "role": "string",      "folders": [        "string"      ],      "folderIds": [        "string"      ],      "read_date": null,      "message_id": "string",      "provider_id": "string",      "body": "string",      "body_plain": "string",      "from_attendee": {        "display_name": "string",        "identifier": "string",        "identifier_type": "EMAIL_ADDRESS"      },      "to_attendees": [        {          "display_name": "string",          "identifier": "string",          "identifier_type": "EMAIL_ADDRESS"        }      ],      "cc_attendees": [        {          "display_name": "string",          "identifier": "string",          "identifier_type": "EMAIL_ADDRESS"        }      ],      "bcc_attendees": [        {          "display_name": "string",          "identifier": "string",          "identifier_type": "EMAIL_ADDRESS"        }      ],      "reply_to_attendees": [        {          "display_name": "string",          "identifier": "string",          "identifier_type": "EMAIL_ADDRESS"        }      ],      "subject": "string",      "has_attachments": true,      "origin": "string",      "in_reply_to": {        "message_id": "string",        "id": null      },      "thread_id": "string",      "attachments": [        {          "id": "string",          "name": "string",          "size": 0,          "extension": "string",          "mime": "string",          "cid": "string",          "inline": true        }      ],      "headers": [        {          "name": "string",          "value": "string"        }      ],      "gateway": {        "references": [          "string"        ],        "unread": true,        "flagged": true,        "answered": true,        "draft": true,        "is_auto_reply": true,        "is_bounce": true,        "special_use": "string",        "size": 0      },      "kind": "1_meta"    }  ],  "cursor": "string"}

Address book (not offered) GET

Not offered: it needs contacts scopes no mailbox grants. Always 422 `errors/not_supported_by_provider`.

Send an email POST

JSON, or multipart with each nested field (`to`, `cc`, `bcc`, `from`, `custom_headers`, `tracking_options`) as a JSON string and each attachment a file part. `custom_headers` may hold `X-*`, `List-Unsubscribe`, `List-Unsubscribe-Post`, `Reply-To`, `Content-Type` (text/plain makes a text-only mail) and, ours, `In-Reply-To` and `References`; anything else, or a line break, is 400 `errors/invalid_headers`. At most 500 recipients and 25 MB of attachments. `Idempotency-Key` makes a retry answer the first send (keys are per mailbox: the same key on two mailboxes is two sends). A mailbox that is not `OK` is still queued (`gateway.account_status` says its status). 404 means the mailbox is gone; a `reply_to` that names no mail is 422 `errors/parent_mail_not_found`.