API Changelog

Next-gen API v1.28

Copy page

Sender sharing

An account can now share a sender with the accounts below it. POST /brands/default/senders and PATCH /brands/default/senders/{sender_id} accept three new fields:

• sharing: who, beyond the owning account, may use the sender. none (the default) keeps it to the owning account, sub_accounts shares it with direct sub-accounts, descendants shares it with every account below at any depth, and accounts shares it only with the accounts you list.
• shared_with_account_ids: the accounts allowed to use the sender, with accounts only. 1 to 100 account IDs.
• excluded_account_ids: the accounts denied the sender, with sub_accounts or descendants only. Up to 100 account IDs. Under descendants, excluding an account also excludes every account below it.

Both lists can only name accounts below the owning account.

Sender responses now include sharing, both lists, and account_id, the account that owns the sender. A sub-account sees the senders shared with it in GET /brands/default/senders, can read them by ID, and can use them wherever a sender_id is accepted. Only the owning account can change or delete a sender.

A sender created before this release reports sharing: "legacy". You can't set legacy: set another mode with PATCH to choose who can use the sender.

Email API rate limit

POST /v2/emails now accepts a limited number of submissions per account in any 60-second window (currently 200). The account is the one the request acts on: the token's own account, or the one named in account_id. Over the limit, the request gets a 429 whose detail gives the limit, the window and retry_in, the number of seconds to wait.

Every 429 from a rate-limited endpoint now also carries a Retry-After header with the same number of seconds.

GET /v2/emails/{email_id} and GET /v2/emails/{email_id}/render now enforce the rate limits they already declared.

Contacts

• PATCH /lists/{list_id}/contacts/{contact_id} accepts remove_tags. With false, the tags in tags are added and no existing tag is removed. The default, true, keeps today's behavior: tags replaces the contact's tags.
• POST /lists/{list_id}/contacts/tag with contact_ids now tags every ID that is a contact of the list, and returns the others in skipped_contact_ids. Before, one unknown ID failed the whole request with a 400.
• POST /lists/{list_id}/contacts/tag and POST /lists/{list_id}/contacts/untag count a repeated ID in contact_ids once.

Transactional email and attachment settings

usage_limits in GET /accounts/{account_id} and PATCH /accounts/{account_id} has two new fields:

• use_transactional_emails: whether the account can send transactional emails.
• attachment_types: one setting per attachment type POST /v2/emails accepts (csv, doc, docx, calendar, jpeg, pdf, png, xls and xlsx).

GET returns the value that applies to the account: its own, or else the nearest account above it that sets one. With PATCH, a partner can only change a setting that is turned on for its own account, and only on an account it manages. A refused request changes nothing.

Domains

• GET and PATCH /brands/default/domains/default now return the forward domain.
• PATCH /brands/default/domains/default accepts a forward domain that has the same hostname as a tracking or bounce domain that passes verification.
• When a tracking or bounce domain fails verification, each error in the 400 response now includes expected: the DNS record to create (host, type and value).
• A bounce domain that contains a port or user information is now refused.

Fixes

• GET /v2/emails/{email_id} no longer returns a 500 when an email's custom attributes or headers are missing or null.