API

Diffusions

Chaque opération de ce groupe : ce qu'elle accepte, ce qu'elle retourne et les erreurs qu'elle peut renvoyer.

Opérations

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:readLit

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.

Paramètres de requête

limitinteger: Rows per page, 1 to 100.
Au moins 1Au plus 100Par défaut25
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.
De 1 à 64 caractères

Retourne

200BroadcastList

A page of broadcasts, newest first.

Erreurs

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

Les erreurs que toute opération peut renvoyer401403404500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.list()broadcasts.listAll()broadcasts.iterate()
CLI: openemail broadcasts list
MCP: listBroadcasts

POST`/broadcasts`

Send to audiences

emails:sendaudiences:readEnvoie des e-mails

Prend en charge 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 contact that has unsubscribed from every one of the chosen audiences it is in, and except an address on the suppression list. 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. They are escaped in html, and any other {{…}} is left as written. With template, the same values are passed as props, but only the props the template declares, so a template that declares none of them is sent unchanged.

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. An html or text body that does not place {{unsubscribeUrl}} itself gets a one-line footer with the link. A template is sent as it is, so put {{unsubscribeUrl}} in the template. The link opens a page with an Unsubscribe button, and following it marks the person unsubscribed in every audience this broadcast was sent to (unsubscribedAt on GET /audiences/{id}/contacts). Their other audiences, 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.

En-têtes

Idempotency-Keystring: Makes a retry safe. Reusing one with a different body is a 422.
Jusqu'à 255 caractèresMotif^[A-Za-z0-9_.:-]+$

Corps de la requête

audienceIdsstring[]Obligatoire

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.

De 1 à 10 éléments

fromstring | objectObligatoire

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

emailstringObligatoire: Jusqu'à 320 caractères
namestring: Jusqu'à 128 caractères

replyTostring | object

Where replies go, the same for every copy.

emailstringObligatoire: Jusqu'à 320 caractères
namestring: Jusqu'à 128 caractères

subjectstring

Required unless a template supplies it. Takes merge fields: {{firstName}}, {{lastName}}, {{name}}, {{email}}, {{unsubscribeUrl}}, each with an optional fallback after a bar, such as {{firstName|there}}.

Jusqu'à 998 caractèresPar défaut""

htmlstring

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

Jusqu'à 1000000 caractères

textstring

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

Jusqu'à 1000000 caractères

templateobject

A stored template instead of html and text. The merge values are passed as props, but only the ones the template declares, and the template is not given a footer, so declare and place unsubscribeUrl yourself.

idstringObligatoire: De 1 à 128 caractères
versioninteger: Plus de 0Au plus 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.

Par défaut{}

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.

De 3 à 64 caractères

Retourne

200object

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

objectstring: L'un de"broadcast"
idstring: The durable handle, brd_ + 24 hex.
statusstring: 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.
L'un de"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.
L'un de"live""test"
sourcestring: Where it was started: api for a key, oauth for a connected app, composer for the app, mcp for an assistant.
L'un de"api""oauth""composer""mcp""ai""form"
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.
Peut être null
scheduledAtstring: When the sending is due to start. Null for a broadcast sent straight away.
Peut être nullFormatdate-time
startedAtstring: When the sending reached the first people. Null until then.
Peut être 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.
Peut être nullFormatdate-time
cancelledAtstring: Peut être nullFormatdate-time
createdAtstring: Formatdate-time
updatedAtstring: Formatdate-time
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: L'un de"broadcast"
idstring: The durable handle, brd_ + 24 hex.
statusstring: 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.
L'un de"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.
L'un de"live""test"
sourcestring: Where it was started: api for a key, oauth for a connected app, composer for the app, mcp for an assistant.
L'un de"api""oauth""composer""mcp""ai""form"
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.
Peut être null
scheduledAtstring: When the sending is due to start. Null for a broadcast sent straight away.
Peut être nullFormatdate-time
startedAtstring: When the sending reached the first people. Null until then.
Peut être 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.
Peut être nullFormatdate-time
cancelledAtstring: Peut être nullFormatdate-time
createdAtstring: Formatdate-time
updatedAtstring: Formatdate-time
replayedboolean: True when an Idempotency-Key replayed an earlier call, false for a new broadcast.

Erreurs

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. 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.

Les erreurs que toute opération peut renvoyer400401500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.send()
CLI: openemail broadcasts send
MCP: sendToAudience

POST`/broadcasts/preview`

Count who a broadcast would reach

audiences:readLit

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.

Corps de la requête

audienceIdsstring[]Obligatoire: 1 to 10 audience ids, the same list you would send.
De 1 à 10 éléments

Retourne

200BroadcastPreview

The counts. Nothing was sent.

Erreurs

404: audience_not_found on audienceIds when an id names no audience in this workspace.
422: invalid_parameter on audienceIds when it is empty or holds more than 10 ids, unknown_parameter for any other key in the body.

Les erreurs que toute opération peut renvoyer400401403500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.preview()
CLI: openemail broadcasts preview
MCP: previewAudienceSend

GET`/broadcasts/analytics`

Broadcast analytics across broadcasts

emails:readLit

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.

Paramètres de requête

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.
Jusqu'à 4000 caractères
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.
Au moins 1Au plus 1095Par défaut30
minutesinteger: The window in minutes, which wins over days when both are sent.
Au moins 1Au plus 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.
L'un de"minute""hour""day"Par défaut"day"
offsetMinutesinteger: Minutes east of UTC to cut the buckets in. Pass -new Date().getTimezoneOffset() for the local zone.
Au moins -840Au plus 840Par défaut0

Retourne

200BroadcastAnalytics

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

Erreurs

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

Les erreurs que toute opération peut renvoyer400401403404500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.analytics()
CLI: openemail broadcasts analytics
MCP: getBroadcastAnalytics

GET`/broadcasts/{id}`

Retrieve a broadcast

emails:readLit

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.

Paramètres de chemin

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

Retourne

200Broadcast

The broadcast.

Erreurs

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

Les erreurs que toute opération peut renvoyer400401403422500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.get()
CLI: openemail broadcasts get
MCP: getBroadcast

GET`/broadcasts/{id}/recipients`

List the recipients of a broadcast

emails:readLit

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.

Paramètres de chemin

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

Paramètres de requête

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.
L'un de"pending""sent""delivered""opened""not_opened""clicked""bounced""complained""failed""unsubscribed"
qstring: Searches the address and the name, ignoring case.
Jusqu'à 200 caractères
limitinteger: Rows per page, 1 to 200.
Au moins 1Au plus 200Par défaut50
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.

Retourne

200BroadcastRecipientList

A page of recipients, by address.

Erreurs

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

Les erreurs que toute opération peut renvoyer400401403422500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.listRecipients()broadcasts.listAllRecipients()broadcasts.iterateRecipients()
CLI: openemail broadcasts list-recipients
MCP: listBroadcastRecipients

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

Retrieve one copy of a broadcast

emails:readLit

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.

Paramètres de chemin

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

Retourne

200BroadcastRecipientContent

The copy and its content.

Erreurs

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

Les erreurs que toute opération peut renvoyer400401403422500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.getRecipient()
CLI: openemail broadcasts get-recipient
MCP: getBroadcastRecipient

GET`/broadcasts/{id}/stats`

Broadcast statistics

emails:readLit

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.

Paramètres de chemin

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

Paramètres de requête

grainstring: Bucket width of the series.
L'un de"minute""hour""day"Par défaut"hour"
offsetMinutesinteger: Minutes east of UTC to cut the buckets in. Pass -new Date().getTimezoneOffset() for the local zone.
Au moins -840Au plus 840Par défaut0
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.
Au moins 1Au plus 1095
minutesinteger: The window in minutes, which wins over days when both are sent.
Au moins 1Au plus 1576800

Retourne

200BroadcastStats

Totals, the window and the series.

Erreurs

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.

Les erreurs que toute opération peut renvoyer400401403500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.stats()
CLI: openemail broadcasts stats
MCP: getBroadcastStats

POST`/broadcasts/{id}/cancel`

Cancel a broadcast

emails:sendSupprime

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.

Paramètres de chemin

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

Retourne

200Broadcast

The broadcast, now cancelled.

Erreurs

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.

Les erreurs que toute opération peut renvoyer400401403422500Catalogue des erreurs

Aussi disponible dans

SDK: broadcasts.cancel()
CLI: openemail broadcasts cancel
MCP: cancelBroadcast

Objets

`Broadcast`object

objectstring: L'un de"broadcast"
idstring: The durable handle, brd_ + 24 hex.
statusstring: 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.
L'un de"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.
L'un de"live""test"
sourcestring: Where it was started: api for a key, oauth for a connected app, composer for the app, mcp for an assistant.
L'un de"api""oauth""composer""mcp""ai""form"
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.
Peut être null
scheduledAtstring: When the sending is due to start. Null for a broadcast sent straight away.
Peut être nullFormatdate-time
startedAtstring: When the sending reached the first people. Null until then.
Peut être 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.
Peut être nullFormatdate-time
cancelledAtstring: Peut être nullFormatdate-time
createdAtstring: Formatdate-time
updatedAtstring: Formatdate-time

`BroadcastAnalytics`object

objectstring

L'un de"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

L'un de"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: L'un de"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

`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: L'un de"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.
Peut être null

`BroadcastPreview`object

objectstring: L'un de"broadcast_preview"
audienceIdsstring[]: The audiences as sent.
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: L'un de"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.
Peut être null
emailstring: The address the copy went to.
namestring: Peut être null
statusstring: The status of the copy on the send log: queued, scheduled, sending, sent, failed or cancelled.
sentAtstring: Peut être nullFormatdate-time
deliveredAtstring: When the receiving server accepted it, the first email.delivered.
Peut être nullFormatdate-time
bouncedAtstring: When it bounced, the first email.bounced.
Peut être nullFormatdate-time
complainedAtstring: When the person reported it as spam, the first email.complained.
Peut être nullFormatdate-time
failurestring: Why the copy failed, when it did.
Peut être null
opensinteger: Opens recorded, without the ones image proxies and scanners make. 0 when tracking was off.
firstOpenAtstring: Peut être nullFormatdate-time
clicksinteger: Clicks recorded on tracked links, without scanners.
firstClickAtstring: Peut être nullFormatdate-time
unsubscribedAtstring: When this person unsubscribed from one of the broadcast's audiences after it was sent, through its link or otherwise.
Peut être nullFormatdate-time

`BroadcastRecipientContent`object

objectstring: L'un de"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.
Peut être null
emailstring: The address the copy went to.
namestring: Peut être null
statusstring: The status of the copy on the send log: queued, scheduled, sending, sent, failed or cancelled.
sentAtstring: Peut être nullFormatdate-time
deliveredAtstring: When the receiving server accepted it, the first email.delivered.
Peut être nullFormatdate-time
bouncedAtstring: When it bounced, the first email.bounced.
Peut être nullFormatdate-time
complainedAtstring: When the person reported it as spam, the first email.complained.
Peut être nullFormatdate-time
failurestring: Why the copy failed, when it did.
Peut être null
opensinteger: Opens recorded, without the ones image proxies and scanners make. 0 when tracking was off.
firstOpenAtstring: Peut être nullFormatdate-time
clicksinteger: Clicks recorded on tracked links, without scanners.
firstClickAtstring: Peut être nullFormatdate-time
unsubscribedAtstring: When this person unsubscribed from one of the broadcast's audiences after it was sent, through its link or otherwise.
Peut être 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.
Peut être null
textstring: Peut être null

`BroadcastRecipientList`object

objectstring: L'un de"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.
Peut être null

`BroadcastStats`object

objectstring

L'un de"broadcast_stats"

broadcastIdstring

grainstring

L'un de"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.

Peut être 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

Diffusions

Opérations

Paramètres de requête

Retourne

Erreurs

Aussi disponible dans

En-têtes

Corps de la requête

Retourne

Erreurs

Aussi disponible dans

Corps de la requête

Retourne

Erreurs

Aussi disponible dans

Paramètres de requête

Retourne

Erreurs

Aussi disponible dans

Paramètres de chemin

Retourne

Erreurs

Aussi disponible dans

Paramètres de chemin

Paramètres de requête

Retourne

Erreurs

Aussi disponible dans

Paramètres de chemin

Retourne

Erreurs

Aussi disponible dans

Paramètres de chemin

Paramètres de requête

Retourne

Erreurs

Aussi disponible dans

Paramètres de chemin

Retourne

Erreurs

Aussi disponible dans

Objets

Broadcastobject

BroadcastAnalyticsobject

BroadcastCountsobject

BroadcastListobject

BroadcastPreviewobject

BroadcastRecipientobject

BroadcastRecipientContentobject

BroadcastRecipientListobject

BroadcastStatsobject

Votre boîte de réception,à vos conditions.

`Broadcast`object

`BroadcastAnalytics`object

`BroadcastCounts`object

`BroadcastList`object

`BroadcastPreview`object

`BroadcastRecipient`object

`BroadcastRecipientContent`object

`BroadcastRecipientList`object

`BroadcastStats`object

Votre boîte de réception,
à vos conditions.