API reference

Send one email. The endpoint every integration starts with, and the only one many ever use. 200 when the status is queued, 202 when it is scheduled.

Arguments

from string required

Sender, as an address or as "Name <address>". The domain must be verified on this workspace, or be onboarding@emails.sh while you are testing.

to string[] required

Recipients. Up to 50 addresses counted across to, cc, and bcc together.

subject string required

html string

HTML body. Give html, text, or both.

text string

Plain-text body. Sent as the alternative part when html is present.

cc string[]

bcc string[]

reply_to string | string[]

Where replies go, if not the from address.

headers Record<string, string>

Extra headers, for example List-Unsubscribe.

attachments { filename, content_base64, content_type? }[]

Base64 bytes with no data: prefix. 40 MB total per message, counted after base64 encoding.

tags Record<string, string>

Labels stored with the email and echoed on every webhook for it.

send_at string

When to send it, up to 30 days out. An ISO 8601 timestamp such as 2026-08-04T09:00:00Z, a relative offset such as "in 1 min", or a clock time such as "tomorrow at 9am", read as UTC. Omit to send now.

idempotency_key string

Your own id for this send. A repeat within 24 hours returns the first result instead of sending again.

Returns{ id, status: "queued" | "scheduled" }

{ from: string, to: string[], subject: string, html?: string, text?: string, cc?: string[], bcc?: string[], reply_to?: string | string[], headers?: Record<string, string>, attachments?: { filename, content_base64, content_type? }[], tags?: Record<string, string>, send_at?: string, idempotency_key?: string }

Send up to 100 emails in one request. Each entry succeeds or fails on its own, and the response keeps the order you sent them in.

Arguments

emails Send[] required

Up to 100 send bodies, each exactly as emails.send takes one.

Returns{ data: ({ id, status } | { id: null, status: "failed", error })[] }

{ emails: Send[] }

Status and delivery events for one email: when it was accepted, when the receiving server took it, and the bounce or complaint if there was one.

Arguments

id string required

The id a send returned.

Returns{ id, status, to, subject, created_at, events[] }

{ id: string }

Every sending domain on the workspace, with the DNS records a pending one still needs.

Takes no arguments.

Returns{ domains: Domain[] }

{ }

Add a sending domain. The response carries every DNS record to publish, so setup can finish without opening the dashboard.

Arguments

domain string required

A domain or subdomain you control, for example mail.acme.com.

Returns{ id, domain, verification_status, records[] }

{ domain: string }

One domain, in the shape the list gives it, with the DNS records still to publish if it is pending. An id from another workspace reads as missing.

Arguments

id string required

The id the create response returned.

ReturnsDomain

{ id: string }

Check the records now rather than waiting for the nightly pass. Safe to call repeatedly, and the answer says which records are still missing.

Arguments

id string required

Returns{ domain, verified, records: (Record & { found })[] }

{ id: string }

Remove a domain. Anything still sending from it starts failing, so move senders first.

Arguments

id string required

Returns{ deleted: id }

{ id: string }

Keys on the workspace, with the last time each was used. Values are never listed.

Takes no arguments.

Returns{ api_keys: ApiKey[] }

{ }

Create a key. The value is returned once and never again.

Arguments

name string required

What it is for, so a later reader can revoke the right one.

scopes string[]

Defaults to full access. Give ["mail:send"] to a key that only sends.

Returns{ id, name, key }

{ name: string, scopes?: string[] }

Revoke a key. It stops working on the next request, with no grace period.

Arguments

id string required

Returns{ deleted: id }

{ id: string }

Registered endpoints and the events each is subscribed to. Signing secrets are not listed.

Takes no arguments.

Returns{ webhooks: Webhook[] }

{ }

Register an endpoint. The signing secret comes back once, in this response.

Arguments

url string required

An https endpoint of yours.

events string[]

Defaults to email.delivered, email.bounced, and email.complained.

headers Record<string, string>

Sent with every delivery, for a gateway that wants its own token.

Returns{ id, url, events, secret }

{ url: string, events?: string[], headers?: Record<string, string> }

One endpoint, with its events, whether it is active, and its failure counters. The signing secret is not in a read, at any scope.

Arguments

id string required

ReturnsWebhook

{ id: string }

Change an endpoint in place. Fields you leave out are left alone.

Arguments

id string required

url string

A new https endpoint. Fixing a typo here keeps the id and the secret.

events string[]

Replaces the subscription wholesale rather than adding to it.

active boolean

Turning it back on clears the failure count, so it does not trip on the next miss.

headers Record<string, string>

rotate_secret boolean

Mints a new signing secret and returns it once. The old one keeps signing for a grace window, so the receiver can be redeployed without dropping events.

ReturnsWebhook, plus secret and previous_secret_valid_until when rotate_secret was set

{ id: string, url?: string, events?: string[], active?: boolean, headers?: Record<string, string>, rotate_secret?: boolean }

What each attempt got back: status code, response body, and duration. This is how you tell a broken endpoint from a missing event.

Arguments

webhook_id string

limit number

Defaults to 25.

Returns{ deliveries: Delivery[] }

{ webhook_id?: string, limit?: number }

Remove an endpoint. Queued deliveries for it are dropped.

Arguments

id string required

Returns{ deleted: id }

{ id: string }

Audiences on the workspace. An audience is a named list of contacts with their subscription state.

Takes no arguments.

Returns{ audiences: Audience[] }

{ }

Create an audience.

Arguments

name string required

Returns{ id, name }

{ name: string }

Members of one audience. Each row carries a membership id, which is the id every other member route takes, and a contact_id, which is the workspace-level contact behind it.

Arguments

audience_id string required

status string

subscribed, unsubscribed, pending, or cleaned.

limit number

Defaults to 100, maximum 1000.

offset number

Returns{ contact_count, subscribed_count, contacts: Member[] }

{ audience_id: string, status?: string, limit?: number, offset?: number }

Bulk import into an audience. Up to 10000 rows and 8 MB per call. An address already on the suppression list lands as cleaned rather than subscribed and is counted in held_back.

Arguments

audience_id string required

contacts { email, attributes?, status?, tags? }[] required

Rows to import. A bare array, { contacts: [] }, { data: [] }, or one object all work, and CSV works when the Content-Type says csv.

dry_run boolean

Query parameter. Reports what would happen and writes nothing.

Returns{ created, updated, unchanged, duplicates, tags_added, imported, held_back, skipped, held[], errors[] }

{ audience_id: string, contacts: { email, attributes?, status?, tags? }[], dry_run?: boolean }

Change one membership. Recording an unsubscribe here is what keeps the address from being mailed by the next broadcast.

Arguments

audience_id string required

member string required

The membership id from audiences.members. Not a contact id and not an email address.

attributes Record<string, string>

Per-list merge fields for this membership.

subscribed boolean

Wins over status when both are given.

status string

subscribed, unsubscribed, pending, or cleaned.

ReturnsMember

{ audience_id: string, member: string, attributes?: Record<string, string>, subscribed?: boolean, status?: string }

Remove one membership from an audience. It does not delete the contact, and it does not record an unsubscribe: set status to unsubscribed for that.

Arguments

audience_id string required

member string required

The membership id.

Returns{ deleted: id }

{ audience_id: string, member: string }

Create a broadcast as a draft. The response carries ready and problems[], so you can tell whether it can send yet without trying.

Arguments

from string required

Sender, as an address or as "Name <address>". The domain must be verified on this workspace, or be onboarding@emails.sh while you are testing.

audience_id string

Who it goes to. Required before it can send.

segment_id string

Narrow the audience to the members a segment matches.

topic_id string

The topic the send is filed under, which is what gives it a working one-click opt-out.

subject string

name string

What it is called in the dashboard. Not seen by a recipient.

html string

text string

template_id string

Use a stored template instead of an inline body.

template_version_id string

reply_to string

track_opens boolean

track_clicks boolean

Returns{ id, status: "draft", ready, problems[] }

{ from: string, audience_id?: string, segment_id?: string, topic_id?: string, subject?: string, name?: string, html?: string, text?: string, template_id?: string, template_version_id?: string, reply_to?: string, track_opens?: boolean, track_clicks?: boolean }

Send a draft, or book it. Sending now answers with the recipient count and how many were skipped; booking answers with the time it will go.

Arguments

id string required

scheduled_at string

RFC 3339, strictly in the future and at most 30 days out. Omit to send now.

Returns{ id, status, queued, batches, skipped, recipients } or { id, status, scheduled_at }

{ id: string, scheduled_at?: string }

Send the broadcast to yourself first, rendered exactly as a recipient would get it. It does not change the draft status.

Arguments

id string required

to string | string[] required

Up to 5 addresses.

Returns{ sent, skipped }

{ id: string, to: string | string[] }

The rendered subject and body without sending anything, plus merge_fields saying which fields the audience actually supplies and which are missing.

Arguments

id string required

email string

Render for one member of the audience rather than for a sample.

Returns{ subject, html, text, merge_fields[], audience_sample_size }

{ id: string, email?: string }

The same render as broadcasts.preview, for a body you have not saved. Nothing is written and nothing is sent, so id comes back null.

Arguments

subject string required

html string

One of html or text is required.

text string

from string

Shown back on the preview. It is not resolved against your domains here.

replyTo string

audienceId string

Render against a real member of this audience. Leave it out and the recipient is a placeholder with no attributes.

email string

Which member of audienceId to render for.

Returns{ id: null, subject, html, text, headers, merge_fields[], audience_sample_size }

{ subject: string, html?: string, text?: string, from?: string, replyTo?: string, audienceId?: string, email?: string }

Per-recipient results for one broadcast, with the reason a skipped or failed row did not go.

Arguments

id string required

status string

pending, sent, delivered, bounced, complained, failed, or skipped.

limit number

Defaults to 100, maximum 500.

offset number

Returns{ stats, recipients: Recipient[] }

{ id: string, status?: string, limit?: number, offset?: number }

Call off a scheduled or sending broadcast. Messages already handed to the mail servers have gone.

Arguments

id string required

Returns{ id, status: "cancelled" }

{ id: string }

A saved filter over contacts. Membership is computed when it is read rather than stored, so a segment is never stale.

Arguments

name string required

audience_id string

Leave it out for a workspace-wide segment. status and joined rules need one.

match "all" | "any"

Defaults to all.

rules Rule[]

Up to 20, and never nested.

description string

Returns{ id, name, describes, member_count }

{ name: string, audience_id?: string, match?: "all" | "any", rules?: Rule[], description?: string }

One segment, its rules, and the sentence describing them.

Arguments

id string required

count string

Pass live to recompute member_count now instead of reading the cached one.

ReturnsSegment

{ id: string, count?: string }

Change a segment. Send the whole rule list every time, including the rules you are keeping.

Arguments

id string required

match "all" | "any"

rules Rule[]

Replaced wholesale. Rules are never merged into what is there.

ReturnsSegment

{ id: string, match?: "all" | "any", rules?: Rule[] }

Who a segment currently matches, as a cursor-paged list.

Arguments

id string required

mailable boolean

Only members who are subscribed and not suppressed.

limit number

Defaults to 100, maximum 1000.

after string

The next_after cursor from the previous page.

Returns{ segment_id, total, next_after, members[] }

{ id: string, mailable?: boolean, limit?: number, after?: string }

Read or add tags on a contact. Tags are 1 to 64 characters, hold no comma or newline, are compared without case, and are stored lowercased.

Arguments

id string required

The contact id.

tags string[]

On the POST. A single tag may be given as tag instead.

Returns{ tags, added }

{ id: string, tags?: string[] }

Workspace-level facts about a contact, readable by every segment and automation. These are not the per-list merge fields a broadcast substitutes.

Arguments

id string required

attributes Record<string, string | null>

A merge patch: names you send are written, names you leave out are untouched, and null clears one. 1 to 100 names per call.

Returns{ attributes, changed[] }

{ id: string, attributes?: Record<string, string | null> }

Every address on a contact, whether it is suppressed, and the audiences and topics it is subscribed to. The one call that answers "will this person receive anything".

Arguments

id string required

Returns{ contact_id, subscriptions[] }

{ id: string }

Create a template and its first version.

Arguments

name string required

slug string

What your code names. Derived from the name when you leave it out.

subject string

html string

text string

variables (string | { name, default?, required? })[]

publish boolean

Defaults to false, so a new template starts with nothing live.

Returns{ id, name, slug, published_version_id, latest_version, sendable }

{ name: string, slug?: string, subject?: string, html?: string, text?: string, variables?: (string | { name, default?, required? })[], publish?: boolean }

Write a new draft version. It never publishes, so editing a password reset reaches nobody until you say so.

Arguments

id string required

subject string

Defaults to an empty string.

html string

One of html or text is required.

text string

variables (string | { name, default?, required? })[]

ReturnsVersion

{ id: string, subject?: string, html?: string, text?: string, variables?: (string | { name, default?, required? })[] }

Point live sends at a version.

Arguments

id string required

version_id string

Or version, as a number. Omit both to publish the latest.

Returns{ published_version_id }

{ id: string, version_id?: string }

Render the published version strictly, exactly as a send would. A missing variable is 422 template_variables_missing rather than a blank.

Arguments

id string required

variables Record<string, string>

preheader string

Returns{ subject, html, text, preheader }

{ id: string, variables?: Record<string, string>, preheader?: string }

Render leniently, filling anything you did not supply with a sample. Also returns warnings about markup mail clients will not render.

Arguments

id string required

version_id string

Preview a draft rather than the published version.

variables Record<string, string>

preheader string

Returns{ subject, html, text, values, filled_with_samples, warnings[] }

{ id: string, version_id?: string, variables?: Record<string, string>, preheader?: string }

A named category of mail a recipient can turn off on its own.

Arguments

name string required

key string

Lowercase letters, digits, and hyphens, at least 2 characters. Derived from the name when you leave it out, and never changeable afterwards.

description string

default_opt_in boolean

Defaults to true.

required boolean

Defaults to false. A required topic cannot be switched off.

ReturnsTopic

{ name: string, key?: string, description?: string, default_opt_in?: boolean, required?: boolean }

Read or record what one address has said about your topics. Keyed by address, so somebody who was never in an audience still has a working opt-out.

Arguments

email string required

topic string

A key or an id. On the POST.

subscribed boolean

Leave it out to ask rather than to write.

source string

Where the answer came from, for your own audit trail.

Returns{ email, preference_url, preferences[] }

{ email: string, topic?: string, subscribed?: boolean, source?: string }

Create an automation from a YAML document. It is validated whole: a refusal names the field, says what to write instead, and carries the line number.

Arguments

yaml string required

The document. Post it raw with a YAML or text/plain Content-Type, or wrapped as { yaml }.

Returns{ id, name, slug, trigger, enabled, version, yaml }

{ yaml: string }

GET /v1/automations/:id.yaml. The raw document, with the current version in the x-emailssh-automation-version response header. Comments and key order survive the round trip.

Arguments

id string required

Returnstext/yaml

{ id: string }

PUT /v1/automations/:id.yaml. Replaces the document and writes a new version.

Arguments

id string required

yaml string required

The raw body. This is the write half of the pull and push pair a CI job uses.

Returnstext/yaml

{ id: string, yaml: string }

Start a run of an automation whose trigger is api.call.

Arguments

id string required

email string

One of email or contact_id is required.

contact_id string

idempotency_key string required

Required, not optional. A repeat answers 409 duplicate.

data object

Anything here is readable in the flow as {{ trigger.<name> }}.

Returns{ run_id, status }

{ id: string, email?: string, contact_id?: string, idempotency_key: string, data?: object }

Runs of one automation, with how many steps executed, how many emails went, and the error if it stopped.

Arguments

id string required

status string

running, waiting, completed, stopped, failed, or cancelled.

limit number

Defaults to 50, maximum 200.

Returns{ runs: Run[] }

{ id: string, status?: string, limit?: number }

Sends, deliveries, bounces, complaints, clicks, and opens over a window, as totals and as a series.

Arguments

from string

YYYY-MM-DD in UTC. Defaults to 30 days ago.

to string

YYYY-MM-DD in UTC, inclusive. The window may be at most 400 days.

group_by "day" | "week" | "month"

Defaults to day.

breakdown "domain" | "tag" | "mail_class" | "template"

tag_key string

Required when breakdown is tag.

mail_class "transactional" | "marketing"

domain string

template_id string

tag string

Filter to one tag, written key:value.

Returns{ range, totals, series[], breakdown, notes }

{ from?: string, to?: string, group_by?: "day" | "week" | "month", breakdown?: "domain" | "tag" | "mail_class" | "template", tag_key?: string, mail_class?: "transactional" | "marketing", domain?: string, template_id?: string, tag?: string }

Which tag keys are worth breaking down by, with how much mail each carried. Up to 25.

Arguments

days number

Defaults to 30, clamped to 1 through 400.

Returns{ tag_keys: [{ key, sent }] }

{ days?: number }

Addresses nothing will reach on this workspace, and why each one is there. Rows with is_global set are ours rather than yours.

Arguments

reason "bounce" | "complaint" | "unsub" | "manual"

email string

Ask about one address.

limit number

Defaults to 50, from 1 to 200.

before string

The next_cursor from the previous page.

Returns{ suppressions[], next_cursor, total }

{ reason?: "bounce" | "complaint" | "unsub" | "manual", email?: string, limit?: number, before?: string }

Block an address yourself, for somebody who asked you to stop by replying rather than by clicking.

Arguments

email string required

reason string

Defaults to manual.

ReturnsSuppression

{ email: string, reason?: string }

Clear one, when you know the address is good again. A global row answers 404 and cannot be cleared.

Arguments

id string

Give id or email.

email string

Returns{ deleted }

{ id?: string, email?: string }

Dedicated addresses on the workspace, the shared pools anything else goes through, the default region, and where sending, storage, and compute physically happen.

Takes no arguments.

Returns{ default_region, residency, ips[], shared_pools[] }

{ }

One address, plus a live reverse DNS check: what the PTR should say, what it says, and whether the forward lookup confirms it.

Arguments

id string required

ReturnsIp & { reverse_dns }

{ id: string }

The only two things about an address you can change. POST /v1/ips takes one out of inventory and DELETE /v1/ips/:id hands it back; this route is for pausing one and lowering its cap.

Arguments

id string required

paused boolean

Stop routing mail through it without giving it up.

daily_cap number | null

A non-negative integer, or null for no cap of your own. It can lower the warmup allowance and never raise it.

ReturnsIp

{ id: string, paused?: boolean, daily_cap?: number | null }

Mail that arrived at an address on a domain of yours with inbound turned on.

Arguments

unread_only boolean

thread_id string

limit number

Defaults to 25.

Returns{ messages: Message[] }

{ unread_only?: boolean, thread_id?: string, limit?: number }

One received message with its full body, headers, and attachment list.

Arguments

id string required

ReturnsMessage

{ id: string }

Answer a received message on its own thread, with References and In-Reply-To set for you.

Arguments

id string required

The message you are answering.

html string

text string

Returns{ id, status }

{ id: string, html?: string, text?: string }

Every message in one conversation, oldest first.

Arguments

id string required

ReturnsThread

{ id: string }