API

Broadcasts

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

Operations

One message sent to everybody in one or more audiences, as a separate copy for each person, personalised from the contact with merge fields and carrying a one-click unsubscribe. The sending happens in the background: create the broadcast, then read it for its progress, and list its copies with GET /emails?broadcastId=.

Every copy carries the unsubscribe headers the large mailbox providers require of bulk mail, and a person who unsubscribes is skipped by every later broadcast to those audiences. The suppression list applies as it does to every send.

GET`/broadcasts`

List broadcasts

emails:readReads

Every broadcast in this workspace, newest first, one page at a time, each with live counts. audienceId keeps the ones that were sent to that audience, among others or alone.

The individual messages are not here. List them with GET /emails?broadcastId=.

A key limited to particular addresses or domains lists only the broadcasts sent from an address or domain it holds.

Requires the emails:read scope.

Query parameters

limitinteger: Rows per page, 1 to 100.
At least 1At most 100Default25
cursorstring: A broadcast id. Keyset, not offset: pass the previous page's nextCursor. One that names nothing in this list is a 400 invalid_cursor.
audienceIdstring: Only the broadcasts that included this audience. An id that names no audience answers an empty list rather than a 404.
1 to 64 characters

Returns

200BroadcastList

A page of broadcasts, newest first.

Errors

400: invalid_cursor when cursor names no broadcast in this workspace.
422: invalid_parameter on a limit out of range.

The errors every operation can return401403404429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.list()nextmail.broadcasts.listAll()nextmail.broadcasts.iterate()
Python: broadcasts.list()broadcasts.list_all()broadcasts.iterate()
Ruby: broadcasts.listbroadcasts.list_allbroadcasts.iterate
PHP: broadcasts->listbroadcasts->listAllbroadcasts->iterate
Go: Broadcasts.ListBroadcasts.ListAllBroadcasts.Iterate
Java: broadcasts().listbroadcasts().listAllbroadcasts().iterate
C#: Broadcasts.ListAsyncBroadcasts.ListAllAsyncBroadcasts.IterateAsync
CLI: openemail broadcasts list
MCP: listBroadcasts

POST`/broadcasts`

Send to audiences

emails:sendaudiences:readSends mail

Honours Idempotency-Key

Sends one message to everybody in one or more audiences, as a separate copy for each person. Every copy has exactly one recipient and no cc or bcc, so nobody sees who else it went to, and every copy is an ordinary email with its own msg_ id, events, tracking and webhooks. GET /emails?broadcastId= lists them. Copies are not filed in the Sent folder: the broadcast is the record.

The call answers 202 straight away with the broadcast queued, or scheduled when scheduledAt is set, and the sending happens in the background, 50 people at a time. Read GET /broadcasts/{id} for status and counts as it goes.

WHO GETS IT. Every contact in at least one of audienceIds, counted once however many of them hold it, except a person who has unsubscribed (GET /suppressions/unsubscribes lists them), and except an address on the suppression list. A contact in one of excludeAudienceIds is left out too, even when they are in one of audienceIds. audienceIds cannot name All contacts, the built-in audience that holds everyone this workspace has ever written to, because most of those people never asked for its mail: that is a 422 audience_is_everyone, and a send to it that was scheduled before this rule fails when its time comes. A contact added to one of the audiences after this call but before the sending reaches it is included. counts.recipients is the estimate taken now, and POST /broadcasts/preview returns the same count without sending anything.

QUOTA. The whole send is checked against the plan's monthly sends before anything is written. A broadcast the allowance cannot cover is refused with 429 send_quota_exceeded and leaves nothing behind. Each copy counts as one send.

PERSONALISATION. subject, html and text take merge fields, filled in for each person: {{firstName}}, {{lastName}}, {{name}}, {{email}}, {{unsubscribeUrl}}. Each takes a fallback after a bar, such as {{firstName|there}}, used when the contact has no value for it. The values come from the contact: the first name is the first word of its name and the last name is the rest. A custom field of the contact is {{attributes.<key>}}, such as {{attributes.plan|Free}}, and reads as its fallback, or as nothing, when the contact has no such field. Every value is escaped in html, and any other {{…}} is left as written. With template, the five values above are passed as props, but only the props the template declares, except unsubscribeUrl, which every template receives.

UNSUBSCRIBE. Every copy carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click, which is what lets a mail client offer its own unsubscribe button and what the large mailbox providers require of bulk mail. A body or a template that does not place {{unsubscribeUrl}} itself gets a short footer with the link, in English, which also names the sender and shows the postal address once marketingPostalAddress is set on PATCH /settings. A template receives unsubscribeUrl whether it declares it or not, so one that places it decides where the link goes. The link opens a page with an Unsubscribe button, and following it unsubscribes the person from all of this workspace's marketing mail: every audience they are in shows unsubscribedAt on GET /audiences/{id}/contacts, they are listed on GET /suppressions/unsubscribes, and later broadcasts and automation emails skip them, even after they are added to an audience again or their contact is deleted and made again. Their contact and mail sent to them one message at a time are not affected.

LIMITS. 1 to 10 audiences and up to 8 tags, and every copy also carries the tag broadcast_id. No attachments, cc, bcc, translation or encryption. The body comes from html and or text, or from template, never both.

IDEMPOTENCY. Send an Idempotency-Key and a retry with the same key answers 200 with the broadcast the first call created, with replayed: true and Idempotency-Replayed: true, instead of sending again. The same key with a different body is a 422 idempotency_key_reuse. Without a key, sending the same body twice sends the broadcast twice.

Requires the emails:send and audiences:read scopes.

Headers

Idempotency-Keystring: Makes a retry safe. Reusing one with a different body is a 422.
Up to 255 charactersPattern^[A-Za-z0-9_.:-]+$

Request body

audienceIdsstring[]Required

1 to 10 audience ids. A contact in several of them gets one copy. Each id has to name an audience in this workspace, or nothing is sent.

1 to 10 items

excludeAudienceIdsstring[]

Up to 10 audiences whose members are left out, even when they are also in one of audienceIds, such as the customers who already bought. All contacts may be named here.

Up to 10 items

segmentIdstring

A saved segment that narrows the audiences: only the contacts that match its conditions get a copy, such as the people who opened in the last 90 days. The conditions are read when the broadcast is sent or scheduled and kept with it, so editing the segment later changes nothing that is already on its way. Resending to the people who did not open leaves the segment out, because they already passed it.

1 to 64 characters

fromstring | objectRequired

The sender, as on POST /emails: an address the key may send as, bare or with a name.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

replyTostring | object

Where replies go, the same for every copy.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

subjectstring

Required unless a template supplies it. Takes merge fields: {{firstName}}, {{lastName}}, {{name}}, {{email}}, {{unsubscribeUrl}}, and {{attributes.<key>}} for a custom field of the contact, each with an optional fallback after a bar, such as {{firstName|there}}.

Up to 998 charactersDefault""

htmlstring

The HTML body, with the same merge fields, their values escaped. Without {{unsubscribeUrl}} in it, a one-line unsubscribe footer is added.

Up to 1000000 characters

textstring

The plain text body, with the same merge fields. Without {{unsubscribeUrl}} in it, an unsubscribe line is added.

Up to 1000000 characters

templateobject

A stored template instead of html and text. The merge values are passed as props, but only the ones the template declares, except unsubscribeUrl, which every template receives. A template that does not place it gets the same footer as a body.

idstringRequired: 1 to 128 characters
versioninteger: More than 0At most 100000
propsRecord<string, any>
slotsRecord<string, any>

trackingobject

Open and link tracking for every copy. A field left out takes the from address setting, as on POST /emails.

opensboolean
clicksboolean

tagsRecord<string, string>

Up to 8 tags, copied onto every copy beside broadcast_id, which the server adds.

Default{}

utmobject

Campaign tags added to every http and https link in the body: source, medium, campaign, term and content become utm_source and the rest, so the visits show up in your web analytics. A link that already carries one keeps its own value, and the unsubscribe link never gets them. Values are 1 to 100 characters, campaign up to 200.

sourcestring: 1 to 100 characters
mediumstring: 1 to 100 characters
campaignstring: 1 to 200 characters
termstring: 1 to 100 characters
contentstring: 1 to 100 characters

abTestobject

An A/B test. variants holds 2 to 4 versions, each a subject, or a body as html and or text, that replaces the broadcast's own, so {} keeps the broadcast as it is. testPercent (5 to 50, 20 unless set) of the people get a variant, split evenly between them, and metric (opens unless set, or clicks) picks the winner once waitMinutes (30 to 4320, 240 unless set) have passed since the test went out. Everybody else then gets the winning variant. The rate counts the people who opened or clicked out of the copies each variant sent, a tie goes to the earlier variant, and with nothing to compare the first variant wins. A template broadcast can only vary the subject.

variantsobject[]Required

2 to 4 items

subjectstring: 1 to 998 characters
htmlstring: 1 to 1000000 characters
textstring: 1 to 1000000 characters

testPercentinteger

At least 5At most 50Default20

metricstring

One of"opens""clicks"Default"opens"

waitMinutesinteger

At least 30At most 4320Default240

scheduledAtstring

When to start: an ISO 8601 instant or a duration such as PT2H, in the future and at most 365 days out. Left out, the sending starts straight away.

3 to 64 characters

Returns

200object

An Idempotency-Key replayed an earlier call. This is that broadcast, not a new one.

objectstring: One of"broadcast"
idstring: The durable handle, brd_ + 24 hex.
statusstring: draft is saved and not sent: POST /broadcasts/{id}/send sends it. scheduled waits for scheduledAt. queued waits for the sending to start. sending is walking the audiences, or has finished walking them while copies are still waiting to go. sent means every copy handed over has been sent or settled. cancelled was stopped by POST /broadcasts/{id}/cancel. failed means the whole broadcast stopped: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written, and lastError says which.
One of"draft""scheduled""queued""sending""sent""cancelled""failed"
modestring: The mode of the key that created it. A broadcast made with a test key sends its copies the way any test send goes: accepted and marked sent, and delivered to nobody.
One of"live""test"
sourcestring: Where it was started: api for a key, oauth for a connected app, composer for the app, mcp for an assistant.
One of"api""oauth""composer""mcp""ai""form""mail-app""booking"
audienceIdsstring[]: The audiences it was sent to, each once.
fromstring: The address every copy is sent from.
subjectstring: The subject as written, merge fields and all, so it reads the same for every copy. Empty when a template supplies the subject.
countsBroadcastCounts
lastErrorstring: Why the broadcast failed, or the most recent copy that could not be written and why. Null while nothing has gone wrong.
Can be null
scheduledAtstring: When the sending is due to start. Null for a broadcast sent straight away.
Can be nullFormatdate-time
startedAtstring: When the sending reached the first people. Null until then.
Can be nullFormatdate-time
completedAtstring: When the last person was reached and every copy had been written. Copies can still be waiting to go after it, which is why status can read sending with this set.
Can be nullFormatdate-time
cancelledAtstring: Can be nullFormatdate-time
createdAtstring: Formatdate-time
updatedAtstring: Formatdate-time
contentBroadcastContent
replayedboolean: True when an Idempotency-Key replayed an earlier call, false for a new broadcast.

202object

Accepted. The Location header names the broadcast; nothing has been sent yet.

objectstring: One of"broadcast"
idstring: The durable handle, brd_ + 24 hex.
statusstring: draft is saved and not sent: POST /broadcasts/{id}/send sends it. scheduled waits for scheduledAt. queued waits for the sending to start. sending is walking the audiences, or has finished walking them while copies are still waiting to go. sent means every copy handed over has been sent or settled. cancelled was stopped by POST /broadcasts/{id}/cancel. failed means the whole broadcast stopped: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written, and lastError says which.
One of"draft""scheduled""queued""sending""sent""cancelled""failed"
modestring: The mode of the key that created it. A broadcast made with a test key sends its copies the way any test send goes: accepted and marked sent, and delivered to nobody.
One of"live""test"
sourcestring: Where it was started: api for a key, oauth for a connected app, composer for the app, mcp for an assistant.
One of"api""oauth""composer""mcp""ai""form""mail-app""booking"
audienceIdsstring[]: The audiences it was sent to, each once.
fromstring: The address every copy is sent from.
subjectstring: The subject as written, merge fields and all, so it reads the same for every copy. Empty when a template supplies the subject.
countsBroadcastCounts
lastErrorstring: Why the broadcast failed, or the most recent copy that could not be written and why. Null while nothing has gone wrong.
Can be null
scheduledAtstring: When the sending is due to start. Null for a broadcast sent straight away.
Can be nullFormatdate-time
startedAtstring: When the sending reached the first people. Null until then.
Can be nullFormatdate-time
completedAtstring: When the last person was reached and every copy had been written. Copies can still be waiting to go after it, which is why status can read sending with this set.
Can be nullFormatdate-time
cancelledAtstring: Can be nullFormatdate-time
createdAtstring: Formatdate-time
updatedAtstring: Formatdate-time
contentBroadcastContent
replayedboolean: True when an Idempotency-Key replayed an earlier call, false for a new broadcast.

Errors

403: insufficient_scope unless the key holds both emails:send and audiences:read, or from_address_forbidden when the key may not send as from.
404: audience_not_found on audienceIds when an id names no audience in this workspace. Nothing is written.
409: domain_not_sendable: the from domain is known to this workspace but cannot sign mail yet, the same refusal POST /emails gives.
422: no_recipients on audienceIds when the audiences are empty or everybody in them has unsubscribed or is suppressed. audience_is_everyone on audienceIds when one of them is All contacts, the built-in audience. invalid_parameter or unknown_parameter on a field that does not validate: no body, html or text alongside template, no subject without a template, more than 10 audiences or 8 tags, or a scheduledAt that is not in the future or more than 365 days out. template_not_found, template_not_published and the other template refusals on template.*, or a prop that does not fit the template on template.props.<name>.
429: send_quota_exceeded: the plan cannot cover a copy for every recipient this month. Nothing was written, and no broadcast is left behind.
rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in Retry-After.

The errors every operation can return400401500Error catalog

Also available in

TypeScript: nextmail.broadcasts.send()
Python: broadcasts.send()
Ruby: broadcasts.send
PHP: broadcasts->send
Go: Broadcasts.Send
Java: broadcasts().send
C#: Broadcasts.SendAsync
CLI: openemail broadcasts send
MCP: sendToAudience

POST`/broadcasts/preview`

Count who a broadcast would reach

audiences:readReads

The numbers POST /broadcasts would work from, without sending anything or writing anything: how many people it would reach, how many are skipped because they have unsubscribed, and how many because their address is suppressed. A contact in several of the audiences counts once.

The count is taken at the moment of the call. Contacts who join or leave before the send starts change it.

Requires the audiences:read scope.

Request body

audienceIdsstring[]Required: 1 to 10 audience ids, the same list you would send.
1 to 10 items
excludeAudienceIdsstring[]: Up to 10 audiences whose members are left out, even when they are also in one of audienceIds, such as the customers who already bought. All contacts may be named here.
Up to 10 items
segmentIdstring: A saved segment that narrows the audiences: only the contacts that match its conditions get a copy, such as the people who opened in the last 90 days. The conditions are read when the broadcast is sent or scheduled and kept with it, so editing the segment later changes nothing that is already on its way. Resending to the people who did not open leaves the segment out, because they already passed it.
1 to 64 characters

Returns

200BroadcastPreview

The counts. Nothing was sent.

Errors

404: audience_not_found on audienceIds when an id names no audience in this workspace.
422: audience_is_everyone on audienceIds when one of them is All contacts, the built-in audience, which no broadcast can go to. invalid_parameter on audienceIds when it is empty or holds more than 10 ids, unknown_parameter for any other key in the body.

The errors every operation can return400401403429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.preview()
Python: broadcasts.preview()
Ruby: broadcasts.preview
PHP: broadcasts->preview
Go: Broadcasts.Preview
Java: broadcasts().preview
C#: Broadcasts.PreviewAsync
CLI: openemail broadcasts preview
MCP: previewAudienceSend

GET`/broadcasts/analytics`

Broadcast analytics across broadcasts

emails:readReads

The numbers behind the Analytics tab of the Broadcasts page, in one request: how the live broadcasts sent inside a window did, added up and as a series cut to grain, plus one row per broadcast so they can be compared.

A copy counts when it was sent, or written if it has not gone yet, inside the window, and everything that happened to it afterwards counts with it, so an open today of a copy sent last week is in a 30 day window but not in a 1 day one. Test mode broadcasts are left out. totals and series cover the broadcasts in broadcastIds, or every one when it is left out, and broadcasts always lists every broadcast in the window. The series counts each person once, at the first time it happened to them.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds, and the rest are left out as if they did not exist.

Requires the emails:read scope.

Query parameters

broadcastIdsstring: Comma separated broadcast ids, at most 50, that totals and series add up. Leave it out for every broadcast in the window. A repeated id counts once, and one with no copy in the window adds nothing.
Up to 4000 characters
daysinteger: How far back to look. The window starts at the beginning of its first bucket in the offset you asked for, so the oldest bucket is a whole one, and ends now.
At least 1At most 1095Default30
minutesinteger: The window in minutes, which wins over days when both are sent.
At least 1At most 1576800
grainstring: How wide one bucket is, and the shape of its key: YYYY-MM-DD for a day, YYYY-MM-DDTHH for an hour, YYYY-MM-DDTHH:MM for a minute.
One of"minute""hour""day"Default"day"
offsetMinutesinteger: Minutes east of UTC to cut the buckets in. Pass -new Date().getTimezoneOffset() for the local zone.
At least -840At most 840Default0

Returns

200BroadcastAnalytics

The window, the totals, the series and every broadcast in the window.

Errors

422: invalid_parameter on broadcastIds for more than 50 ids, on days, minutes or offsetMinutes out of range, or on an unknown grain.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.analytics()
Python: broadcasts.analytics()
Ruby: broadcasts.analytics
PHP: broadcasts->analytics
Go: Broadcasts.Analytics
Java: broadcasts().analytics
C#: Broadcasts.AnalyticsAsync
CLI: openemail broadcasts analytics
MCP: getBroadcastAnalytics

GET`/broadcasts/{id}`

Retrieve a broadcast

emails:readReads

One broadcast with counts read live from its copies, which makes this the call to poll while it sends. status settles on sent once every copy handed over has gone out or failed, and on failed or cancelled when it stopped early.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Returns

200Broadcast

The broadcast.

Errors

404: broadcast_not_found when the id names no broadcast in this workspace.

The errors every operation can return400401403422429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.get()
Python: broadcasts.get()
Ruby: broadcasts.get
PHP: broadcasts->get
Go: Broadcasts.Get
Java: broadcasts().get
C#: Broadcasts.GetAsync
CLI: openemail broadcasts get
MCP: getBroadcast

PATCH`/broadcasts/{id}`

Update a draft or a scheduled broadcast

emails:sendaudiences:readChanges data

A partial update: a field left out keeps what it holds, and null clears replyTo, html, text, template or utm. Sending any of html, text or template replaces the body as a whole.

A draft takes every change and stays a draft. A scheduled broadcast takes changes until its sending starts, each checked the way POST /broadcasts checks a new one, and counts.recipients is counted again. scheduledAt moves a scheduled broadcast to another time. Any other broadcast answers 409 broadcast_not_editable.

A key limited to particular addresses or domains changes only broadcasts sent from an address or domain it holds.

Requires the emails:send and audiences:read scopes.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Request body

audienceIdsstring[]

The new audiences, replacing the old list.

Up to 10 items

excludeAudienceIdsstring[]

Up to 10 audiences whose members are left out, even when they are also in one of audienceIds, such as the customers who already bought. All contacts may be named here.

Up to 10 items

segmentIdstring

Can be null1 to 64 characters

fromstring | object

A new sender the key may send as.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

replyTostring | object

Where replies go. Null takes it away.

Can be null

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

subjectstring

A new subject, with merge fields.

Up to 998 characters

htmlstring

A new HTML body. Sending html, text or template replaces the body as a whole.

Can be nullUp to 1000000 characters

textstring

A new plain text body.

Can be nullUp to 1000000 characters

templateobject

A stored template instead of html and text. Null takes it away.

Can be null

idstringRequired: 1 to 128 characters
versioninteger: More than 0At most 100000
propsRecord<string, any>
slotsRecord<string, any>

trackingobject

Open and link tracking for every copy.

opensboolean
clicksboolean

tagsRecord<string, string>

The new tags, replacing the old ones, up to 8.

utmobject

Can be null

sourcestring: 1 to 100 characters
mediumstring: 1 to 100 characters
campaignstring: 1 to 200 characters
termstring: 1 to 100 characters
contentstring: 1 to 100 characters

abTestobject

Can be null

variantsobject[]Required

2 to 4 items

subjectstring: 1 to 998 characters
htmlstring: 1 to 1000000 characters
textstring: 1 to 1000000 characters

testPercentinteger

At least 5At most 50Default20

metricstring

One of"opens""clicks"Default"opens"

waitMinutesinteger

At least 30At most 4320Default240

scheduledAtstring

A new start for a scheduled broadcast, in the future and at most 365 days out. A draft refuses it: give the time to POST /broadcasts/{id}/send.

3 to 64 characters

Returns

200Broadcast

The broadcast as it stands after the change, with its content.

Errors

403: from_address_forbidden when the key may not send as from.
404: broadcast_not_found when the id names no broadcast in this workspace, audience_not_found on an audience id.
409: broadcast_not_editable: the broadcast is queued, sending or finished. stream_paused while the broadcast lane of the workspace is paused.
422: no_recipients when a scheduled broadcast would reach nobody, invalid_parameter on scheduledAt for a draft, which is scheduled when it is sent, or on a field that does not validate.
429: send_quota_exceeded: the plan cannot cover the scheduled broadcast after the change.
rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in Retry-After.

The errors every operation can return400401500Error catalog

Also available in

TypeScript: nextmail.broadcasts.update()
Python: broadcasts.update()
Ruby: broadcasts.update
PHP: broadcasts->update
Go: Broadcasts.Update
Java: broadcasts().update
C#: Broadcasts.UpdateAsync
CLI: openemail broadcasts update
MCP: updateBroadcast

GET`/broadcasts/{id}/recipients`

List the recipients of a broadcast

emails:readReads

Everybody the broadcast went to, one row per copy, sorted by address: the copy id, its status, when it was sent and delivered, whether it bounced or was reported as spam, how often it was opened and clicked, and whether the person unsubscribed after it went out.

Opens and clicks leave out image proxies and link scanners, and stay 0 when the broadcast was sent with tracking off. Keyset paging: pass nextCursor back as cursor, with the same filter and q.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Query parameters

filterstring: Keeps one group: pending (still queued or sending), sent, delivered, opened, not_opened (sent and never opened), clicked, bounced, complained, failed (failed or cancelled) or unsubscribed.
One of"pending""sent""delivered""opened""not_opened""clicked""bounced""complained""failed""unsubscribed"
qstring: Searches the address and the name, ignoring case.
Up to 200 characters
limitinteger: Rows per page, 1 to 200.
At least 1At most 200Default50
cursorstring: The previous page's nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 invalid_cursor.

Returns

200BroadcastRecipientList

A page of recipients, by address.

Errors

404: broadcast_not_found when the id names no broadcast in this workspace.

The errors every operation can return400401403422429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.listRecipients()nextmail.broadcasts.listAllRecipients()nextmail.broadcasts.iterateRecipients()
Python: broadcasts.list_recipients()broadcasts.list_all_recipients()broadcasts.iterate_recipients()
Ruby: broadcasts.list_recipientsbroadcasts.list_all_recipientsbroadcasts.iterate_recipients
PHP: broadcasts->listRecipientsbroadcasts->listAllRecipientsbroadcasts->iterateRecipients
Go: Broadcasts.ListRecipientsBroadcasts.ListAllRecipientsBroadcasts.IterateRecipients
Java: broadcasts().listRecipientsbroadcasts().listAllRecipientsbroadcasts().iterateRecipients
C#: Broadcasts.ListRecipientsAsyncBroadcasts.ListAllRecipientsAsyncBroadcasts.IterateRecipientsAsync
CLI: openemail broadcasts list-recipients
MCP: listBroadcastRecipients

GET`/broadcasts/{id}/recipients/{emailId}`

Retrieve one copy of a broadcast

emails:readReads

One person's copy: the same row GET /broadcasts/{id}/recipients lists, plus the subject, HTML and text exactly as that person received them, with the merge fields filled in and their own unsubscribe link. The HTML is from before open and click tracking was added.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.
emailIdstringRequired: The emailId of the copy, from the recipients list.

Returns

200BroadcastRecipientContent

The copy and its content.

Errors

404: broadcast_not_found for an unknown broadcast, recipient_not_found for a copy that is not part of it.

The errors every operation can return400401403422429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.getRecipient()
Python: broadcasts.get_recipient()
Ruby: broadcasts.get_recipient
PHP: broadcasts->getRecipient
Go: Broadcasts.GetRecipient
Java: broadcasts().getRecipient
C#: Broadcasts.GetRecipientAsync
CLI: openemail broadcasts get-recipient
MCP: getBroadcastRecipient

GET`/broadcasts/{id}/stats`

Broadcast statistics

emails:readReads

How the broadcast performed: copies sent, delivered, bounced, reported as spam and failed, and how many people opened, clicked and unsubscribed, as totals and as a series cut to grain. The series counts each person once, at the first time it happened to them, so it adds up to the totals.

Send days or minutes to also read what happened lately: window then counts the copies delivered, bounced, reported, opened, clicked and unsubscribed inside it, and series keeps only its buckets. totals always covers the whole broadcast.

A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:read scope.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Query parameters

grainstring: Bucket width of the series.
One of"minute""hour""day"Default"hour"
offsetMinutesinteger: Minutes east of UTC to cut the buckets in. Pass -new Date().getTimezoneOffset() for the local zone.
At least -840At most 840Default0
daysinteger: Reads a window too: how far back it reaches. It starts at the beginning of its first grain bucket and ends now. Leave it and minutes out for no window.
At least 1At most 1095
minutesinteger: The window in minutes, which wins over days when both are sent.
At least 1At most 1576800

Returns

200BroadcastStats

Totals, the window and the series.

Errors

404: broadcast_not_found when the id names no broadcast in this workspace.
422: invalid_parameter on days, minutes or offsetMinutes out of range, or on an unknown grain.

The errors every operation can return400401403429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.stats()
Python: broadcasts.stats()
Ruby: broadcasts.stats
PHP: broadcasts->stats
Go: Broadcasts.Stats
Java: broadcasts().stats
C#: Broadcasts.StatsAsync
CLI: openemail broadcasts stats
MCP: getBroadcastStats

POST`/broadcasts/{id}/cancel`

Cancel a broadcast

emails:sendDeletes

Stops a broadcast that is scheduled, queued or sending, including one that has reached everybody while some copies are still waiting to go. Nobody else is added, and every copy still waiting to go is cancelled. A copy already being handed over finishes, and copies that have gone cannot be recalled, so counts.sent keeps them. No body.

Cancelling a cancelled broadcast answers it as it stands, so a retry is safe.

A key limited to particular addresses or domains cancels only broadcasts sent from an address or domain it holds. Any other broadcast answers 404 broadcast_not_found, as if it did not exist.

Requires the emails:send scope.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Returns

200Broadcast

The broadcast, now cancelled.

Errors

404: broadcast_not_found when the id names no broadcast in this workspace.
409: broadcast_not_cancellable: every copy has already gone out, or the broadcast failed.

The errors every operation can return400401403422429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.cancel()
Python: broadcasts.cancel()
Ruby: broadcasts.cancel
PHP: broadcasts->cancel
Go: Broadcasts.Cancel
Java: broadcasts().cancel
C#: Broadcasts.CancelAsync
CLI: openemail broadcasts cancel
MCP: cancelBroadcast

POST`/broadcasts/drafts`

Save a broadcast draft

emails:sendaudiences:readChanges data

Saves a broadcast with status draft. Nothing is sent, nothing counts against the plan and the audiences may still be empty, so a draft can be written over several sittings. PATCH /broadcasts/{id} changes it, POST /broadcasts/{id}/send sends or schedules it, and GET /broadcasts/{id} returns what it holds in content.

The body takes the fields POST /broadcasts takes, except scheduledAt, and only from is required. The sender, the audiences and a template are checked as they are saved.

Requires the emails:send and audiences:read scopes.

Request body

audienceIdsstring[]

Up to 10 audience ids. May be empty in a draft, but not when it is sent.

Up to 10 itemsDefault[]

excludeAudienceIdsstring[]

Up to 10 audiences whose members are left out, even when they are also in one of audienceIds, such as the customers who already bought. All contacts may be named here.

Up to 10 items

segmentIdstring

1 to 64 characters

fromstring | objectRequired

The sender, an address the key may send as, bare or with a name.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

replyTostring | object

Where replies go, the same for every copy.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

subjectstring

At most 998 characters, with merge fields. Needed before sending unless a template supplies it.

Up to 998 charactersDefault""

htmlstring

HTML body, at most 1,000,000 characters, with merge fields.

Up to 1000000 characters

textstring

Plain text body, at most 1,000,000 characters, with merge fields.

Up to 1000000 characters

templateobject

A stored template instead of html and text, never beside them.

idstringRequired: 1 to 128 characters
versioninteger: More than 0At most 100000
propsRecord<string, any>
slotsRecord<string, any>

trackingobject

Open and link tracking for every copy.

opensboolean
clicksboolean

tagsRecord<string, string>

Up to 8 tags every copy carries.

Default{}

utmobject

sourcestring: 1 to 100 characters
mediumstring: 1 to 100 characters
campaignstring: 1 to 200 characters
termstring: 1 to 100 characters
contentstring: 1 to 100 characters

abTestobject

variantsobject[]Required

2 to 4 items

subjectstring: 1 to 998 characters
htmlstring: 1 to 1000000 characters
textstring: 1 to 1000000 characters

testPercentinteger

At least 5At most 50Default20

metricstring

One of"opens""clicks"Default"opens"

waitMinutesinteger

At least 30At most 4320Default240

Returns

201Broadcast

The draft, with its content. The Location header names it. Nothing was sent.

Errors

403: insufficient_scope unless the key holds both emails:send and audiences:read, or from_address_forbidden when the key may not send as from.
404: audience_not_found on audienceIds or excludeAudienceIds.
422: audience_is_everyone when audienceIds names All contacts, invalid_parameter or unknown_parameter on a field that does not validate, and the template refusals on template.*.

The errors every operation can return400401429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.createDraft()
Python: broadcasts.create_draft()
Ruby: broadcasts.create_draft
PHP: broadcasts->createDraft
Go: Broadcasts.CreateDraft
Java: broadcasts().createDraft
C#: Broadcasts.CreateDraftAsync
CLI: openemail broadcasts create-draft
MCP: createBroadcastDraft

POST`/broadcasts/test`

Send a test of a broadcast

emails:sendSends mail

Sends one copy of a broadcast to up to 5 addresses, to read it before it goes out. Without to it goes to the account address of the person the key or app acts for, the workspace owner for an API key. The merge fields are filled from the contact that has the address when there is one and from a sample name otherwise, the subject starts with [Test], the unsubscribe footer is added as it would be and its link does nothing. Opens and clicks are not tracked, and utm is applied to the links.

No broadcast is created and nobody joins an audience. Each copy counts as one send.

Requires the emails:send scope.

Request body

fromstring | objectRequired

The sender, an address the key may send as.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

replyTostring | object

Where replies go.

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

subjectstring

Required unless a template supplies it, with merge fields.

Up to 998 charactersDefault""

htmlstring

HTML body with merge fields.

Up to 1000000 characters

textstring

Plain text body with merge fields.

Up to 1000000 characters

templateobject

A stored template instead of html and text.

idstringRequired: 1 to 128 characters
versioninteger: More than 0At most 100000
propsRecord<string, any>
slotsRecord<string, any>

utmobject

sourcestring: 1 to 100 characters
mediumstring: 1 to 100 characters
campaignstring: 1 to 200 characters
termstring: 1 to 100 characters
contentstring: 1 to 100 characters

to(string | object)[]

1 to 5 addresses. Left out, the test goes to the account address of the person the key or app acts for.

1 to 5 items

emailstringRequired: Up to 320 characters
namestring: Up to 128 characters

Returns

200BroadcastTest

The copies that were sent.

Errors

403: from_address_forbidden when the key may not send as from.
409: domain_not_sendable: the from domain cannot sign mail yet.
422: invalid_parameter on a field that does not validate: no body, html or text beside template, no subject without a template, or more than 5 addresses in to. The template refusals on template.*.
429: send_quota_exceeded: the plan has no sends left this month.
rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in Retry-After.

The errors every operation can return400401404500Error catalog

Also available in

TypeScript: nextmail.broadcasts.sendTest()
Python: broadcasts.send_test()
Ruby: broadcasts.send_test
PHP: broadcasts->sendTest
Go: Broadcasts.SendTest
Java: broadcasts().sendTest
C#: Broadcasts.SendTestAsync
CLI: openemail broadcasts send-test
MCP: sendBroadcastTest

POST`/broadcasts/{id}/send`

Send a draft

emails:sendaudiences:readSends mail

Turns a draft into a broadcast that goes out: queued straight away, or scheduled with scheduledAt. The draft is checked the way POST /broadcasts checks a new broadcast: it needs an audience, a body, a subject or a template that supplies one, somebody to reach and room in the plan for every copy. A broadcast that is not a draft answers 409 broadcast_not_draft, so a repeated call never sends twice. The body is optional.

Requires the emails:send and audiences:read scopes.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Request body

scheduledAtstring: When to start: an ISO 8601 instant or a duration such as PT2H, in the future and at most 365 days out. Left out, the sending starts straight away.
3 to 64 characters

Returns

202Broadcast

Accepted. The broadcast is queued or scheduled, and nothing has been sent yet.

Errors

403: from_address_forbidden when the key may no longer send as the draft's from.
404: broadcast_not_found, or audience_not_found when an audience of the draft is gone.
409: broadcast_not_draft, stream_paused while the broadcast lane is paused, or domain_not_sendable.
422: no_recipients when the draft has no audience or nobody in it can be sent to, invalid_parameter when it has no body or no subject, or on a scheduledAt that is not in the future or more than 365 days out.
429: send_quota_exceeded: the plan cannot cover a copy for every recipient this month.
rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in Retry-After.

The errors every operation can return400401500Error catalog

Also available in

TypeScript: nextmail.broadcasts.sendDraft()
Python: broadcasts.send_draft()
Ruby: broadcasts.send_draft
PHP: broadcasts->sendDraft
Go: Broadcasts.SendDraft
Java: broadcasts().sendDraft
C#: Broadcasts.SendDraftAsync
CLI: openemail broadcasts send-draft
MCP: sendBroadcastDraft

POST`/broadcasts/{id}/duplicate`

Duplicate a broadcast

emails:sendaudiences:readChanges data

Copies any broadcast into a new draft: the same sender, audiences, left-out audiences, subject, body or template, tracking, tags and campaign tags, without the time it was scheduled for. The original is not changed and nothing is sent. No body.

Requires the emails:send and audiences:read scopes.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Returns

201Broadcast

The new draft. The Location header names it.

Errors

403: from_address_forbidden when the key may not send as the original from.
404: broadcast_not_found, or audience_not_found when an audience of the original is gone.
422: The template refusals on template.* when the original template no longer resolves.

The errors every operation can return400401429500Error catalog

Also available in

TypeScript: nextmail.broadcasts.duplicate()
Python: broadcasts.duplicate()
Ruby: broadcasts.duplicate
PHP: broadcasts->duplicate
Go: Broadcasts.Duplicate
Java: broadcasts().duplicate
C#: Broadcasts.DuplicateAsync
CLI: openemail broadcasts duplicate
MCP: duplicateBroadcast

POST`/broadcasts/{id}/resend`

Resend to the people who did not open

emails:sendaudiences:readSends mail

Creates a new broadcast with the same content for the people the first one reached and who have not opened it, optionally under a new subject. Somebody who has unsubscribed since, or whose address is now suppressed, is skipped. The new broadcast names the first in content.resendOf and counts against the plan like any send. The first broadcast has to be sent and to have tracked opens, or the call answers 409 resend_unavailable. The body is optional.

Opens are counted from the tracking pixel, so a person whose mail app blocks images can look like they never opened.

Requires the emails:send and audiences:read scopes.

Path parameters

idstringRequired: A brd_ id from POST /broadcasts or GET /broadcasts.

Request body

subjectstring: A new subject for the second try, with merge fields. Left out, the first subject is used.
1 to 998 characters
scheduledAtstring: When to start, in the future and at most 365 days out. Left out, the sending starts straight away.
3 to 64 characters

Returns

202Broadcast

Accepted. The new broadcast, queued or scheduled. The Location header names it.

Errors

404: broadcast_not_found when the id names no broadcast in this workspace.
409: resend_unavailable: the broadcast has not finished going out or did not track opens. stream_paused while the broadcast lane is paused.
422: no_recipients when everybody it reached has opened it.
429: send_quota_exceeded: the plan cannot cover a copy for every recipient this month.
rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in Retry-After.

The errors every operation can return400401403500Error catalog

Also available in

TypeScript: nextmail.broadcasts.resend()
Python: broadcasts.resend()
Ruby: broadcasts.resend
PHP: broadcasts->resend
Go: Broadcasts.Resend
Java: broadcasts().resend
C#: Broadcasts.ResendAsync
CLI: openemail broadcasts resend
MCP: resendBroadcast

Objects

`Broadcast`object

objectstring: One of"broadcast"
idstring: The durable handle, brd_ + 24 hex.
statusstring: draft is saved and not sent: POST /broadcasts/{id}/send sends it. scheduled waits for scheduledAt. queued waits for the sending to start. sending is walking the audiences, or has finished walking them while copies are still waiting to go. sent means every copy handed over has been sent or settled. cancelled was stopped by POST /broadcasts/{id}/cancel. failed means the whole broadcast stopped: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written, and lastError says which.
One of"draft""scheduled""queued""sending""sent""cancelled""failed"
modestring: The mode of the key that created it. A broadcast made with a test key sends its copies the way any test send goes: accepted and marked sent, and delivered to nobody.
One of"live""test"
sourcestring: Where it was started: api for a key, oauth for a connected app, composer for the app, mcp for an assistant.
One of"api""oauth""composer""mcp""ai""form""mail-app""booking"
audienceIdsstring[]: The audiences it was sent to, each once.
fromstring: The address every copy is sent from.
subjectstring: The subject as written, merge fields and all, so it reads the same for every copy. Empty when a template supplies the subject.
countsBroadcastCounts
lastErrorstring: Why the broadcast failed, or the most recent copy that could not be written and why. Null while nothing has gone wrong.
Can be null
scheduledAtstring: When the sending is due to start. Null for a broadcast sent straight away.
Can be nullFormatdate-time
startedAtstring: When the sending reached the first people. Null until then.
Can be nullFormatdate-time
completedAtstring: When the last person was reached and every copy had been written. Copies can still be waiting to go after it, which is why status can read sending with this set.
Can be nullFormatdate-time
cancelledAtstring: Can be nullFormatdate-time
createdAtstring: Formatdate-time
updatedAtstring: Formatdate-time
contentBroadcastContent

`BroadcastAnalytics`object

objectstring

One of"broadcast_analytics"

sincestring

The start of the window, floored to the start of its first bucket in the local time of offsetMinutes.

Formatdate-time

untilstring

The end of the window, the moment of the read.

Formatdate-time

grainstring

One of"minute""hour""day"

offsetMinutesinteger

The offset the buckets were cut in, as sent or 0.

broadcastIdsstring[]

The ids totals and series cover, each once. Empty means every broadcast in the window.

totalsobject

Added up over the copies of the broadcasts in broadcastIds that were sent inside the window. opened, clicked and unsubscribed count people; opens and clicks count events.

broadcastsinteger: How many broadcasts those copies belong to.
recipientsinteger
pendinginteger: Copies still queued, scheduled or sending.
sentinteger
deliveredinteger
bouncedinteger
complainedinteger
failedinteger: Copies that failed or were cancelled.
openedinteger
clickedinteger
unsubscribedinteger
opensinteger
clicksinteger

seriesobject[]

SPARSE, oldest first: one bucket per grain in which something happened to those copies, each counted once, at the first time it happened.

bucketstring: YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, in the offset asked for.
sentinteger
deliveredinteger
openedinteger
clickedinteger
unsubscribedinteger

broadcastsobject[]

Every broadcast with a copy sent inside the window, newest first, whatever broadcastIds picks, each with the same counts over its copies in the window. Use it to compare broadcasts or to pick ids.

idstring
subjectstring
statusstring: One of"draft""scheduled""queued""sending""sent""cancelled""failed"
sentAtstring: When it started sending, or when it was created if it has not.
Formatdate-time
recipientsinteger
pendinginteger: Copies still queued, scheduled or sending.
sentinteger
deliveredinteger
bouncedinteger
complainedinteger
failedinteger: Copies that failed or were cancelled.
openedinteger
clickedinteger
unsubscribedinteger
opensinteger
clicksinteger

`BroadcastContent`object

subjectstringRequired

The subject as written, merge fields and all.

htmlstringRequired

The HTML body as written, before the unsubscribe footer is added.

Can be null

textstringRequired

The plain text body as written.

Can be null

templateobjectRequired

The stored template the body comes from, with the props and slots it was given.

Can be null

idstring
versioninteger
propsobject
slotsobject

replyTostringRequired

Where replies go.

Can be null

trackingobjectRequired

Open and link tracking for every copy.

Can be null

opensboolean
clicksboolean

tagsRecord<string, string>Required

excludeAudienceIdsstring[]Required

The audiences whose members are left out.

segmentIdstringRequired

The saved segment that narrows the audiences, or null.

Can be null

utmobjectRequired

The campaign tags added to the links.

Can be null

sourcestring: 1 to 100 characters
mediumstring: 1 to 100 characters
campaignstring: 1 to 200 characters
termstring: 1 to 100 characters
contentstring: 1 to 100 characters

abTestobjectRequired

The A/B test, or null. Beside the test as it was asked for, phase says where it stands: testing while the variants go out, waiting until decidesAt, and winner once winner names the variant everybody else gets. GET /broadcasts/{id}/stats returns how each variant did.

Can be null

variantsobject[]Required

2 to 4 items

subjectstring: 1 to 998 characters
htmlstring: 1 to 1000000 characters
textstring: 1 to 1000000 characters

testPercentinteger

At least 5At most 50Default20

metricstring

One of"opens""clicks"Default"opens"

waitMinutesinteger

At least 30At most 4320Default240

phasestring

Null until the sending starts.

Can be nullOne of"testing""waiting""winner"

winnerstring

The id of the winning variant, a to d, once it is picked.

Can be null

decidesAtstring

While waiting, when the winner is picked.

Can be nullFormatdate-time

decidedAtstring

When the winner was picked.

Can be nullFormatdate-time

resendOfstringRequired

For a broadcast made by POST /broadcasts/{id}/resend, the broadcast it sends again to the people who did not open it.

Can be null

`BroadcastCounts`object

Where the broadcast stands. The first four are kept by the sending itself; the last five are counted live from the copies, by the send status each one has now.

recipientsinteger: The estimate taken when the broadcast was created: the people it was expected to reach. It does not move afterwards, so contacts who join or leave while it sends make created differ from it.
createdinteger: Copies written so far, one per person reached. Each is an ordinary email with its own msg_ id.
skippedinteger: People passed over while sending because their address was on the suppression list by the time the sending reached them.
failedToQueueinteger: People whose copy could not be written at all. lastError on the broadcast names the most recent one and why.
queuedinteger: Copies waiting to be sent.
sendinginteger: Copies being handed over right now.
sentinteger: Copies that went out.
failedinteger: Copies whose send failed. GET /emails/{id} on one says why.
cancelledinteger: Copies a cancel stopped before they went.

`BroadcastList`object

objectstring: One of"list"
dataBroadcast[]
hasMoreboolean: True when another page follows. Pass nextCursor back as cursor to read it.
nextCursorstring: The id of the last row on this page, or null on the last page.
Can be null

`BroadcastPreview`object

objectstring: One of"broadcast_preview"
audienceIdsstring[]: The audiences as sent.
excludeAudienceIdsstring[]: The audiences whose members were left out, as sent, or empty.
segmentIdstring: The segment the counts were narrowed to, as sent, or null.
Can be null
recipientsinteger: The people a broadcast to these audiences would reach now. A contact in several of them counts once.
unsubscribedinteger: Contacts in these audiences who would be skipped because they have unsubscribed from every one of them they are in.
suppressedinteger: Subscribed contacts who would be skipped because their address is on the suppression list after a bounce or a complaint, or because somebody added it there.

`BroadcastRecipient`object

objectstring: One of"broadcast_recipient"
emailIdstring: The msg_ id of this person's copy. GET /emails/{id} reads it as a sent email.
contactIdstring: The contact it went to, null if deleted since.
Can be null
emailstring: The address the copy went to.
namestring: Can be null
statusstring: The status of the copy on the send log: queued, scheduled, sending, sent, bounced, failed or cancelled.
sentAtstring: Can be nullFormatdate-time
deliveredAtstring: When the receiving server accepted it, the first email.delivered.
Can be nullFormatdate-time
bouncedAtstring: When it bounced, the first email.bounced.
Can be nullFormatdate-time
complainedAtstring: When the person reported it as spam, the first email.complained.
Can be nullFormatdate-time
failurestring: Why the copy failed, when it did.
Can be null
opensinteger: Opens recorded, without the ones image proxies and scanners make. 0 when tracking was off.
firstOpenAtstring: Can be nullFormatdate-time
clicksinteger: Clicks recorded on tracked links, without scanners.
firstClickAtstring: Can be nullFormatdate-time
unsubscribedAtstring: When this person unsubscribed from one of the broadcast's audiences after it was sent, through its link or otherwise.
Can be nullFormatdate-time

`BroadcastRecipientContent`object

objectstring: One of"broadcast_recipient"
emailIdstring: The msg_ id of this person's copy. GET /emails/{id} reads it as a sent email.
contactIdstring: The contact it went to, null if deleted since.
Can be null
emailstring: The address the copy went to.
namestring: Can be null
statusstring: The status of the copy on the send log: queued, scheduled, sending, sent, bounced, failed or cancelled.
sentAtstring: Can be nullFormatdate-time
deliveredAtstring: When the receiving server accepted it, the first email.delivered.
Can be nullFormatdate-time
bouncedAtstring: When it bounced, the first email.bounced.
Can be nullFormatdate-time
complainedAtstring: When the person reported it as spam, the first email.complained.
Can be nullFormatdate-time
failurestring: Why the copy failed, when it did.
Can be null
opensinteger: Opens recorded, without the ones image proxies and scanners make. 0 when tracking was off.
firstOpenAtstring: Can be nullFormatdate-time
clicksinteger: Clicks recorded on tracked links, without scanners.
firstClickAtstring: Can be nullFormatdate-time
unsubscribedAtstring: When this person unsubscribed from one of the broadcast's audiences after it was sent, through its link or otherwise.
Can be nullFormatdate-time
subjectstring: The subject as this person got it, merge fields filled in.
htmlstring: The HTML as this person got it, before open and click tracking was added.
Can be null
textstring: Can be null

`BroadcastRecipientList`object

objectstring: One of"list"
dataBroadcastRecipient[]
hasMoreboolean: True when another page follows. Pass nextCursor back as cursor to read it.
nextCursorstring: An opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null

`BroadcastStats`object

objectstring

One of"broadcast_stats"

broadcastIdstring

grainstring

One of"minute""hour""day"

totalsobject

Counts over every copy. opened, clicked and unsubscribed count people; opens and clicks count events.

recipientsinteger
pendinginteger: Copies still queued, scheduled or sending.
sentinteger
deliveredinteger
bouncedinteger
complainedinteger
failedinteger: Copies that failed or were cancelled.
openedinteger
clickedinteger
unsubscribedinteger
opensinteger
clicksinteger

windowobject

Null unless days or minutes was sent. Each count is the copies whose first such event fell inside the window, so it tells you what changed lately, while totals keeps the whole send.

Can be null

sincestring: The start of the window, floored to the start of its first grain bucket in the offset asked for. It ends now.
Formatdate-time
deliveredinteger
bouncedinteger
complainedinteger
openedinteger
clickedinteger
unsubscribedinteger

seriesobject[]

SPARSE, oldest first: one bucket per grain in which something happened. Each counts people by the first time it happened to them. With a window, only the buckets inside it.

bucketstring: YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, in the offset asked for.
deliveredinteger
openedinteger
clickedinteger
unsubscribedinteger

linksobject[]

The 10 links clicked most, the most clicked first. Copies sent without link tracking have none.

urlstring: The address the link points to.
labelstring: The text of the link, when it had any.
Can be null
clicksinteger: Clicks on it, every time it was clicked.
peopleinteger: The people who clicked it at least once.

clientsobject[]

The 8 mail clients people opened the copies in, the most used first, from the opens a person made, not the ones a privacy proxy made.

clientstring: Such as Gmail or Apple Mail, or null when it could not be told.
Can be null
peopleinteger
opensinteger

countriesobject[]

The 10 countries the copies were opened from, the most first, as ISO 3166 codes.

countrystring
peopleinteger

abTestobject

Null unless the broadcast runs an A/B test. Each variant counts the copies it sent in the test and the people who opened or clicked one of them, so the rates can be compared before and after the winner is picked.

Can be null

metricstring

One of"opens""clicks"

winnerstring

The winning variant, or null until it is picked.

Can be null

variantsobject[]

idstring: a to d, in the order of abTest.variants.
subjectstring: The subject of the variant, or null when it keeps the broadcast's own.
Can be null
sentinteger
openedinteger
clickedinteger

`BroadcastTest`object

objectstringRequired: One of"broadcast_test"
emailIdsstring[]Required: The msg_ id of each copy, in the order of to.
tostring[]Required: The addresses, lower-cased.

Broadcasts

Operations

Query parameters

Returns

Errors

Also available in

Headers

Request body

Returns

Errors

Also available in

Request body

Returns

Errors

Also available in

Query parameters

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Path parameters

Request body

Returns

Errors

Also available in

Path parameters

Query parameters

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Path parameters

Query parameters

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Request body

Returns

Errors

Also available in

Request body

Returns

Errors

Also available in

Path parameters

Request body

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Path parameters

Request body

Returns

Errors

Also available in

Objects

Broadcastobject

BroadcastAnalyticsobject

BroadcastContentobject

BroadcastCountsobject

BroadcastListobject

BroadcastPreviewobject

BroadcastRecipientobject

BroadcastRecipientContentobject

BroadcastRecipientListobject

BroadcastStatsobject

BroadcastTestobject

`Broadcast`object

`BroadcastAnalytics`object

`BroadcastContent`object

`BroadcastCounts`object

`BroadcastList`object

`BroadcastPreview`object

`BroadcastRecipient`object

`BroadcastRecipientContent`object

`BroadcastRecipientList`object

`BroadcastStats`object

`BroadcastTest`object

Your inbox,
on your own terms.