Cancel a broadcast

Broadcast ID.

The address this broadcast sends from. name is filled in when the broadcast was given a display name to send under. Left out on a draft that has not picked a sender yet.

The audience this broadcast sends to. When the send starts we turn the audience into a list of recipients, and you can read that list a page at a time with List recipients of a broadcast. Left out on a draft that has not picked an audience yet.

The template this broadcast sends, and the language it sends in. A broadcast sends the template's published version, and the exact version is fixed when the broadcast is prepared for sending, so publishing a new version afterwards does not change what this broadcast sends. Null on a draft that has not chosen a template yet.

Size of the HTML body this broadcast sends, in bytes, or 0 when its content has no HTML part. Measured on the template version the broadcast sends, using the selected language. Recipient merge values can change its size. Returned on a single broadcast read, and absent from the list and from the broadcast that creating, updating, sending or canceling one returns, none of which measure the content. Absent too when the broadcast has no template or its content can no longer be read.

Size of the plain-text body this broadcast sends, in bytes, or 0 when its content has no plain-text part. Measured, and absent, the same way as html_bytes.

What kind of email this is, which decides how suppressions apply to it. A marketing broadcast is held back from every suppressed address. A transactional one still goes to addresses suppressed for a complaint or an unsubscribe, because those suppressions are about marketing mail.

Possible values: marketing, transactional

The IP pool this broadcast sends from, or ipp_shared when it sends through the shared pool. Absent when it sends on your organization's default pool.

Where replies to this broadcast go, if you want them somewhere other than the from address. Absent when you have not set one.

Any custom email headers set on the broadcast. Returned on a single broadcast read and on the broadcast that creating, updating, sending or canceling one returns, and absent from the list. The unsubscribe headers we add ourselves are not included.

Where the broadcast itself has got to, separate from what happened to individual recipients: for that, read sent_count, delivered_count, bounced_count and complained_count below. When it is failed, failure_reason says why.

What to do next about this broadcast, given the state it is in. Each entry names one action and says why it is worth taking. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.

Why the broadcast failed. Set when status is failed, and null the rest of the time.

• empty_audience: There was nobody to send to. Either the audience has no members, or every address in it is suppressed.
• audience_unavailable: The audience no longer exists, so there was nothing to resolve.
• content_invalid: The broadcast could not be set up to send. failure_detail explains what went wrong. It is one of these:
  • The broadcast has no template, or the template it uses no longer exists. Choose an existing template and send the broadcast again.
  • The template has no published version, or its published version has no subject and no body. Publish the template, or add content and publish it.
  • The template uses a loop or reads a value that a broadcast cannot provide. Remove it, or use a contact property instead, then publish the template again.
  • The template requires a language, but the broadcast has not selected one. Set template.language to one of the template's languages and send the broadcast again.
  • The selected language is not available on the published template version. Choose one of that version's languages, or publish a version that includes the selected language.
  • The sending domain is no longer verified. Verify the domain again.
  • The configured IP pool has no usable IP address.
  • We could not hand the prepared message to the delivery system. This is a problem on our side.
• insufficient_funds: There was not enough in the workspace balance to pay for the send.
• quota_exceeded: The send would have gone past your organization's daily or monthly email allowance, whichever runs out first. This can happen when the broadcast is being prepared, or partway through sending if the remaining recipients no longer fit. failure_detail gives you the count and the limit.
• internal_error: Something went wrong on our side. Retry, and open a support ticket if it keeps happening.

Possible values: empty_audience, audience_unavailable, content_invalid, insufficient_funds, quota_exceeded, internal_error, null

A sentence explaining the failure in more detail than failure_reason does, and null when the broadcast has not failed. Show it to the person using your app. Do not write code that reads it, because the wording can change. Branch on failure_reason instead.

Number of recipients after suppressed addresses are removed from the audience. This is 0 until sending starts and the audience becomes a recipient list.

How many recipients the broadcast has been sent to, counting every recipient whose status is processed or later. The number rises while the broadcast is sending and stops changing once the broadcast has finished. These counters are exact. The email stats endpoints report on the same sending but are approximate, so use these numbers when you need the precise count. Absent when the broadcast comes back from creating, updating, sending or canceling it, none of which read the counters. List and single-broadcast reads return 0 when no delivery events are recorded. When counters are unavailable, those reads still return 200 and omit the counters. Read the broadcast again for the numbers.

How many recipients' messages were accepted by their mail server. Absent when sent_count is.

How many recipients the message could not be delivered to at all. Absent when sent_count is.

How many recipients marked the message as spam. Absent when sent_count is.

How many times the message was opened, added up across every recipient. One recipient opening it twice counts twice. Absent when sent_count is.

How many times a link in the message was clicked, added up across every recipient. One recipient clicking twice counts twice. Absent when sent_count is.

The IP addresses this broadcast's messages went out from, up to 100 of them. A broadcast is spread across every address in its pool, so more than one can appear. The receiving mail systems name the address when they deliver, bounce or defer a message, so this stays absent until the first of those comes back. Returned on a single broadcast read, and absent from the list and from the broadcast that creating, updating, sending or canceling one returns, none of which read them. For delivery and latency broken down per address, read the sending-IP stats.

How many distinct recipients opened the message at least once, excluding opens auto-fetched by inbox privacy features (such as Apple Mail Privacy Protection and the Gmail image proxy). A recipient who opened several times, or whose inbox prefetched the message, counts once. Absent when sent_count is.

How many distinct recipients clicked a link in the message at least once. A recipient who clicked several times counts once. Absent when sent_count is.

How many recipients bounced after the message had already been accepted for delivery. A recipient who bounced this way more than once counts once. Absent when sent_count is.

How many distinct recipients a delivery landed for. This is the denominator to measure unique_opens_non_prefetched, unique_clicks and complained_count against. It differs from delivered_count, which reports how many recipients are currently in the delivered state: a recipient who was delivered to and then complained moves to complained_count and leaves delivered_count, but stays here, because the message did reach them. Absent when sent_count is.

Labels on this broadcast, each one a name and a value, that you can filter and search broadcasts by. Use tags for anything you want to find broadcasts by later, and metadata for data you only want handed back to you.

Any JSON you want to keep on the broadcast. We store it and hand it back in webhook payloads, and that is all it does. If you want to search or filter by it, use tags instead.

Whether opens are tracked for this broadcast.

Whether link clicks are tracked for this broadcast.

When the broadcast was created.

When the broadcast is due to send, and absent when it is not scheduled.

When the broadcast started sending. Absent until then. Compare with sent_at, which is when the broadcast finished sending.

When the last recipient was sent to and the broadcast became sent. Null until then. Compare with started_at, which is when the broadcast started sending.

When the broadcast was canceled, and absent if it never was. This is when cancellation was requested, so it is set as soon as the status is canceling and does not move while the remaining sends stop and the status becomes canceled.