API reference

Paths are under https://emails.mydomainshub.com/api/v1. Send Authorization: Bearer mdh_live_… and, with a body, Content-Type: application/json. Errors are described in Errors; limits in Limits.

POST/emails— Send an email
POST/emails/batch— Send up to 100 emails
GET/emails— List emails
GET/emails/{id}— Read an email
PATCH/emails/{id}— Reschedule an email
POST/emails/{id}/cancel— Cancel an email
GET/api-keys— List API keys
POST/api-keys— Create an API key
DELETE/api-keys/{id}— Revoke an API key
GET/domains— List domains
POST/domains— Add a domain
GET/domains/{id}— Read a domain
POST/domains/{id}/verify— Check a domain now
DELETE/domains/{id}— Remove a domain
GET/openapi.json— This API, described

POST`/emails`

Send an email

Queues one email and answers its id. Our worker then sends it — at `scheduled_at`, if you gave one. The answer means queued, not delivered: read the status back, or watch the log.

Takes a sending or a full-access key.

Headers

Field	Type	Description
`Idempotency-Key`	string, 1 to 256 printable ASCII characters	The same key and body within 24 hours answers the first answer again and queues nothing more. See Idempotency.

Body

Field	Type	Description
`from`required	string	The sender: "Name <address>" or a bare address, at a domain verified on your account.
`to`required	string or array of strings	One address or a list. To, cc and bcc together hold at most 50 recipients, each once.
`cc`	string or array of strings	One address or a list.
`bcc`	string or array of strings	One address or a list. Never shown in the message’s headers.
`reply_to`	string or array of strings	One address or a list, for the Reply-To header.
`subject`required	string	One line, 1 to 998 characters.
`html`	string	The HTML body. Give html, text or both.
`text`	string	The plain-text body. Give html, text or both.
`headers`	object of strings	Extra headers: X-* (not X-SES-*), List-Unsubscribe, List-Unsubscribe-Post, List-Id, In-Reply-To, References and Auto-Submitted. At most 20.
`attachments`	array of objects	Up to 20 files, each base64 in `content`. The whole request stays under 4 MB. Executable file types are refused.
`attachments[].filename`required	string
`attachments[].content`required	string
`attachments[].content_type`	string
`tags`	array of objects	Up to 10 name and value pairs (letters, digits, _ and -), each name once, for finding the email later.
`tags[].name`required	string
`tags[].value`required	string
`scheduled_at`	string (ISO 8601 date and time)	When to send it: an ISO 8601 date and time with its zone, at most 72 hours ahead. A time already past sends it at once. Leave it out to send now.

Answer

Field	Type	Description
`id`required	string (uuid)	The email’s id: GET /emails/{id} reads it back.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`, `domain_not_verified`, `account_paused`	The from domain is not verified on this account, the key is limited to another domain, the sandbox refuses the recipient, or sending is paused.
`409`	`validation_error`	The Idempotency-Key was used for a different request in the last 24 hours.
`413`	`validation_error`	The request is larger than 4 MB.
`422`	`validation_error`	The body is not valid (the message says where), or the content check refuses it: a From that imitates a bank, a payments company or a government body, a link through a URL shortener, or a program attached.
`429`	`rate_limited`, `quota_exceeded`	Too many requests with this key, or a daily or monthly cap is reached. Wait for retry-after.

POST`/emails/batch`

Send up to 100 emails

A JSON array of 1 to 100 emails, each shaped as for POST /emails. Every one is checked first, and either all are queued or none is: a refusal names the first email refused as `emails[n]`.

Takes a sending or a full-access key.

Headers

Field	Type	Description
`Idempotency-Key`	string, 1 to 256 printable ASCII characters	The same key and body within 24 hours answers the first answer again and queues nothing more. See Idempotency.

Body

A JSON array of 1 to 100 emails, each with the fields of POST /emails.

Answer

Field	Type	Description
`data`required	array of objects	One id per email, in the order they were sent.
`data[].id`required	string (uuid)	The email’s id: GET /emails/{id} reads it back.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`, `domain_not_verified`, `account_paused`	The from domain is not verified on this account, the key is limited to another domain, the sandbox refuses the recipient, or sending is paused.
`409`	`validation_error`	The Idempotency-Key was used for a different request in the last 24 hours.
`413`	`validation_error`	The request is larger than 4 MB.
`422`	`validation_error`	The body is not valid (the message says where), or the content check refuses it: a From that imitates a bank, a payments company or a government body, a link through a URL shortener, or a program attached.
`429`	`rate_limited`, `quota_exceeded`	Too many requests with this key, or a daily or monthly cap is reached. Wait for retry-after.

GET`/emails`

List emails

The account’s emails, newest first, a page at a time. Filters combine: every one given must match.

Takes a full-access key.

Query parameters

Field	Type	Description
`limit`	integer	How many to answer, 1 to 100. 20 unless given.
`cursor`	string	The `next_cursor` of the page before, as it was given, for the next (older) page.
`status`	one of: queued, sending, sent, delivered, bounced, complained, failed, suppressed, canceled	Only emails with this status.
`to`	string (email address)	Only emails to exactly this address, in to, cc or bcc.
`tag`	string	Only emails with this tag name, or this name:value pair.
`subject`	string	Only emails whose subject contains this text, in any case.
`created_after`	string (ISO 8601 date and time)	Only emails queued at or after this moment (ISO 8601 with its zone).
`created_before`	string (ISO 8601 date and time)	Only emails queued before this moment (ISO 8601 with its zone).

Answer

Field	Type	Description
`object`required	"list"
`data`required	array of objects
`data[].object`required	"email"
`data[].id`required	string (uuid)
`data[].from`required	string
`data[].to`required	array of strings
`data[].cc`required	array of strings
`data[].bcc`required	array of strings
`data[].reply_to`required	array of strings
`data[].subject`required	string
`data[].tags`required	array of objects
`data[].tags[].name`required	string
`data[].tags[].value`required	string
`data[].status`required	one of: queued, sending, sent, delivered, bounced, complained, failed, suppressed, canceled
`data[].status_reason`required	string or null	Why it failed, was suppressed or canceled, as a short code; otherwise null.
`data[].created_at`required	string	When it was queued.
`data[].scheduled_at`required	string	When it may be sent: the moment it was queued, unless scheduled.
`data[].sent_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].delivered_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].bounced_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].complained_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].failed_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].canceled_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].last_event`required	one of: send, delivery, bounce, complaint, reject, delivery_delay, rendering_failure or null	The latest event Amazon SES reported.
`data[].last_event_at`required	string or null	ISO 8601, UTC; null until it happens.
`has_more`required	boolean
`next_cursor`required	string or null	Pass as `cursor` for the next page; null on the last page.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: this takes a full-access key.
`422`	`validation_error`	A filter or the cursor is not valid.

GET`/emails/{id}`

Read an email

Its status, its times and the last event Amazon SES reported. Never its body: bodies are kept 72 hours after sending, for the dashboard only.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The email’s id, as POST /emails answered it.

Answer

Field	Type	Description
`object`required	"email"
`id`required	string (uuid)
`from`required	string
`to`required	array of strings
`cc`required	array of strings
`bcc`required	array of strings
`reply_to`required	array of strings
`subject`required	string
`tags`required	array of objects
`tags[].name`required	string
`tags[].value`required	string
`status`required	one of: queued, sending, sent, delivered, bounced, complained, failed, suppressed, canceled
`status_reason`required	string or null	Why it failed, was suppressed or canceled, as a short code; otherwise null.
`created_at`required	string	When it was queued.
`scheduled_at`required	string	When it may be sent: the moment it was queued, unless scheduled.
`sent_at`required	string or null	ISO 8601, UTC; null until it happens.
`delivered_at`required	string or null	ISO 8601, UTC; null until it happens.
`bounced_at`required	string or null	ISO 8601, UTC; null until it happens.
`complained_at`required	string or null	ISO 8601, UTC; null until it happens.
`failed_at`required	string or null	ISO 8601, UTC; null until it happens.
`canceled_at`required	string or null	ISO 8601, UTC; null until it happens.
`last_event`required	one of: send, delivery, bounce, complaint, reject, delivery_delay, rendering_failure or null	The latest event Amazon SES reported.
`last_event_at`required	string or null	ISO 8601, UTC; null until it happens.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: this takes a full-access key.
`404`	`not_found`	No email with that id belongs to this account.

PATCH`/emails/{id}`

Reschedule an email

Moves an email that is still waiting in the queue to another time. It counts against your caps on the day it was first queued.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The email’s id.

Body

Field	Type	Description
`scheduled_at`required	string (ISO 8601 date and time)	The new moment to send it: ISO 8601 with its zone, at most 72 hours ahead. A time already past sends it at once.

Answer

Field	Type	Description
`object`required	"email"
`id`required	string (uuid)
`status`required	one of: queued, sending, sent, delivered, bounced, complained, failed, suppressed, canceled
`scheduled_at`required	string	ISO 8601, UTC.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: this takes a full-access key.
`404`	`not_found`	No email with that id belongs to this account.
`409`	`validation_error`	The email has already left the queue (or is being sent).
`422`	`validation_error`	scheduled_at is missing, malformed or too far ahead.

POST`/emails/{id}/cancel`

Cancel an email

Cancels an email that is still waiting in the queue — scheduled, or not yet picked up. Its recipients are given back to your caps, and its body is deleted. Cancelling a canceled email answers the same again.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The email’s id.

Answer

Field	Type	Description
`object`required	"email"
`id`required	string (uuid)
`status`required	one of: queued, sending, sent, delivered, bounced, complained, failed, suppressed, canceled
`scheduled_at`required	string	ISO 8601, UTC.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: this takes a full-access key.
`404`	`not_found`	No email with that id belongs to this account.
`409`	`validation_error`	The email has already left the queue (or is being sent).

GET`/api-keys`

List API keys

The account’s keys that are not revoked, newest first. Never a key itself.

Takes a full-access key.

Answer

Field	Type	Description
`object`required	"list"
`data`required	array of objects	The account’s keys that are not revoked, newest first.
`data[].object`required	"api_key"
`data[].id`required	string (uuid)
`data[].name`required	string
`data[].prefix`required	string	The key’s first characters, to tell it apart. Never the key.
`data[].permission`required	one of: full, sending
`data[].domain_id`required	string (uuid) or null	The one domain a sending key is limited to, or null.
`data[].created_at`required	string	ISO 8601, UTC.
`data[].last_used_at`required	string or null	ISO 8601, UTC: moved at most once a minute; null if never used.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: this takes a full-access key.

POST`/api-keys`

Create an API key

Makes a key and answers it once: we keep only a hash, so store it now. The account’s log records it, with the key that made it.

Takes a full-access key.

Body

Field	Type	Description
`name`required	string	What the key is for, 1 to 60 characters, so you can tell keys apart.
`permission`required	one of: full, sending	`sending`: may only send email. `full`: may also read emails, change scheduled ones, and manage keys.
`domain_id`	string (uuid)	A sending key only: limit it to sending from this one domain of your account.

Answer

Field	Type	Description
`object`required	"api_key"
`id`required	string (uuid)
`name`required	string
`prefix`required	string	The key’s first characters, to tell it apart. Never the key.
`permission`required	one of: full, sending
`domain_id`required	string (uuid) or null	The one domain a sending key is limited to, or null.
`created_at`required	string	ISO 8601, UTC.
`last_used_at`required	string or null	ISO 8601, UTC: moved at most once a minute; null if never used.
`key`required	string	The key itself. Shown in this answer only: we keep a hash, and cannot show it again.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used, or the account is closed.
`422`	`validation_error`	The body is not valid; the message says where.

DELETE`/api-keys/{id}`

Revoke an API key

Revokes a key at once: requests with it are refused from now on, and emails it queued that have not left are not sent. Revoking a revoked key answers the same again.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The key’s id, from GET /api-keys.

Answer

Field	Type	Description
`object`required	"api_key"
`id`required	string (uuid)
`revoked`required	true

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: this takes a full-access key.
`404`	`not_found`	No key with that id belongs to this account.

GET`/domains`

List domains

The account’s domains, each with its status and, while it is pending, the DNS records to add.

Takes a full-access key.

Answer

Field	Type	Description
`object`required	"list"
`data`required	array of objects
`data[].object`required	"domain"
`data[].id`required	string (uuid)
`data[].name`required	string
`data[].status`required	one of: pending, verified, failed, removing
`data[].setting_up`required	boolean	True while it is still being set up with Amazon SES.
`data[].created_at`required	string	ISO 8601, UTC.
`data[].verify_by`required	string or null	A pending domain only: 72 hours after it was added, the time to verify it by. Null otherwise.
`data[].verified_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].last_checked_at`required	string or null	ISO 8601, UTC; null until it happens.
`data[].failure`required	object or null	Why it failed, and the record that was missing; null unless failed.
`data[].failure.reason`required	string
`data[].failure.missing_record`required	string or null
`data[].records`required	array of objects	The DNS records to add at your DNS host; empty while it is being set up, and once it has failed.
`data[].records[].record`required	one of: dkim, mail_from_mx, mail_from_spf, dmarc	What it is for: three DKIM records, the MAIL FROM MX and SPF, and DMARC.
`data[].records[].type`required	one of: CNAME, MX, TXT
`data[].records[].name`required	string	The full host name.
`data[].records[].value`required	string	What to put in the record’s value (an MX without its priority).
`data[].records[].priority`	integer	An MX record’s priority.
`data[].records[].required`required	boolean	False only for DMARC, which is suggested, not needed.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: managing domains takes a full-access key.

POST`/domains`

Add a domain

Adds a domain to send from and sets it up with Amazon SES. The answer lists the DNS records to add at your DNS host; Amazon SES verifies the domain once it finds them.

Takes a full-access key.

Body

Field	Type	Description
`name`required	string	The domain you send from, such as acme.ng. Not mydomainshub.com or its subdomains.

Answer

Field	Type	Description
`object`required	"domain"
`id`required	string (uuid)
`name`required	string
`status`required	one of: pending, verified, failed, removing
`setting_up`required	boolean	True while it is still being set up with Amazon SES.
`created_at`required	string	ISO 8601, UTC.
`verify_by`required	string or null	A pending domain only: 72 hours after it was added, the time to verify it by. Null otherwise.
`verified_at`required	string or null	ISO 8601, UTC; null until it happens.
`last_checked_at`required	string or null	ISO 8601, UTC; null until it happens.
`failure`required	object or null	Why it failed, and the record that was missing; null unless failed.
`failure.reason`required	string
`failure.missing_record`required	string or null
`records`required	array of objects	The DNS records to add at your DNS host; empty while it is being set up, and once it has failed.
`records[].record`required	one of: dkim, mail_from_mx, mail_from_spf, dmarc	What it is for: three DKIM records, the MAIL FROM MX and SPF, and DMARC.
`records[].type`required	one of: CNAME, MX, TXT
`records[].name`required	string	The full host name.
`records[].value`required	string	What to put in the record’s value (an MX without its priority).
`records[].priority`	integer	An MX record’s priority.
`records[].required`required	boolean	False only for DMARC, which is suggested, not needed.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used, the plan’s domains are all taken, or the account is closed.
`409`	`validation_error`	The domain is already on this account, or in use on another.
`422`	`validation_error`	The name is not a domain, or is one of ours.

GET`/domains/{id}`

Read a domain

One domain: its status and the DNS records it needs.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The domain’s id, from GET /domains.

Answer

Field	Type	Description
`object`required	"domain"
`id`required	string (uuid)
`name`required	string
`status`required	one of: pending, verified, failed, removing
`setting_up`required	boolean	True while it is still being set up with Amazon SES.
`created_at`required	string	ISO 8601, UTC.
`verify_by`required	string or null	A pending domain only: 72 hours after it was added, the time to verify it by. Null otherwise.
`verified_at`required	string or null	ISO 8601, UTC; null until it happens.
`last_checked_at`required	string or null	ISO 8601, UTC; null until it happens.
`failure`required	object or null	Why it failed, and the record that was missing; null unless failed.
`failure.reason`required	string
`failure.missing_record`required	string or null
`records`required	array of objects	The DNS records to add at your DNS host; empty while it is being set up, and once it has failed.
`records[].record`required	one of: dkim, mail_from_mx, mail_from_spf, dmarc	What it is for: three DKIM records, the MAIL FROM MX and SPF, and DMARC.
`records[].type`required	one of: CNAME, MX, TXT
`records[].name`required	string	The full host name.
`records[].value`required	string	What to put in the record’s value (an MX without its priority).
`records[].priority`	integer	An MX record’s priority.
`records[].required`required	boolean	False only for DMARC, which is suggested, not needed.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: managing domains takes a full-access key.
`404`	`not_found`	No domain with that id belongs to this account.

POST`/domains/{id}/verify`

Check a domain now

Asks Amazon SES about the domain now, as the dashboard’s “Check now” does, and answers what it found.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The domain’s id.

Answer

Field	Type	Description
`object`required	"domain"
`id`required	string (uuid)
`name`required	string
`status`required	one of: pending, verified, failed, removing
`setting_up`required	boolean	True while it is still being set up with Amazon SES.
`created_at`required	string	ISO 8601, UTC.
`verify_by`required	string or null	A pending domain only: 72 hours after it was added, the time to verify it by. Null otherwise.
`verified_at`required	string or null	ISO 8601, UTC; null until it happens.
`last_checked_at`required	string or null	ISO 8601, UTC; null until it happens.
`failure`required	object or null	Why it failed, and the record that was missing; null unless failed.
`failure.reason`required	string
`failure.missing_record`required	string or null
`records`required	array of objects	The DNS records to add at your DNS host; empty while it is being set up, and once it has failed.
`records[].record`required	one of: dkim, mail_from_mx, mail_from_spf, dmarc	What it is for: three DKIM records, the MAIL FROM MX and SPF, and DMARC.
`records[].type`required	one of: CNAME, MX, TXT
`records[].name`required	string	The full host name.
`records[].value`required	string	What to put in the record’s value (an MX without its priority).
`records[].priority`	integer	An MX record’s priority.
`records[].required`required	boolean	False only for DMARC, which is suggested, not needed.

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: managing domains takes a full-access key.
`404`	`not_found`	No domain with that id belongs to this account.

DELETE`/domains/{id}`

Remove a domain

Removes a domain from the account. Refused while emails from it wait to be sent.

Takes a full-access key.

Path

Field	Type	Description
`id`required	string (uuid)	The domain’s id.

Answer

Field	Type	Description
`object`required	"domain"
`id`required	string (uuid)
`deleted`required	true

Errors

Status	name	When
`401`	`unauthorized`	The API key is missing, wrong or revoked.
`429`	`rate_limited`	More than 10 requests a second with this key (bursts of 20). Wait for retry-after.
`500`	`internal_error`	Something failed on our side.
`403`	`forbidden`	A sending key was used: managing domains takes a full-access key.
`404`	`not_found`	No domain with that id belongs to this account.
`409`	`validation_error`	Emails from it still wait to be sent.

GET`/openapi.json`

This API, described

This document: OpenAPI 3.1, generated from the schemas the API validates with.

Takes no key.

Answer

This API’s OpenAPI 3.1 document, as JSON.

POST/emails

Headers

Body

Answer

Errors

POST/emails/batch

Headers

Body

Answer

Errors

GET/emails

Query parameters

Answer

Errors

GET/emails/{id}

Path

Answer

Errors

PATCH/emails/{id}

Path

Body

Answer

Errors

POST/emails/{id}/cancel

Path

Answer

Errors

GET/api-keys

Answer

Errors

POST/api-keys

Body

Answer

Errors

DELETE/api-keys/{id}

Path

Answer

Errors

GET/domains

Answer

Errors

POST/domains

Body

Answer

Errors

GET/domains/{id}

Path

Answer

Errors

POST/domains/{id}/verify

Path

Answer

Errors

DELETE/domains/{id}

Path

Answer

Errors

GET/openapi.json

Answer

POST`/emails`

POST`/emails/batch`

GET`/emails`

GET`/emails/{id}`

PATCH`/emails/{id}`

POST`/emails/{id}/cancel`

GET`/api-keys`

POST`/api-keys`

DELETE`/api-keys/{id}`

GET`/domains`

POST`/domains`

GET`/domains/{id}`

POST`/domains/{id}/verify`

DELETE`/domains/{id}`

GET`/openapi.json`