# Newsletter tools

<Warning>
  **A send cannot be undone.** Every other write on this surface can be republished,
  hidden or repriced. `send_newsletter_broadcast` mails every subscribed address in the
  store, starts before the call returns, and has no cancel. It also spends the store's
  monthly email allowance.
</Warning>

There is deliberately **no tool that returns a subscriber's email address**. A tool
result is read by a model and stored by whatever client is hosting it, which is a
destination the REST API does not have. `get_newsletter_subscriber_count` answers how
many people a broadcast would reach and identifies nobody; when a program genuinely
needs the addresses, read [`GET /api/v1/newsletter-subscribers`](/api-reference/introduction)
under the same `read_newsletter` scope.

### create_newsletter_broadcast

Composes a newsletter broadcast as a DRAFT. Nobody is mailed by this call and there is no field that can make it send: sending is send_newsletter_broadcast, which needs a separate grant. Both subject and body are required.

**Scope:** `write_newsletter`


  <ParamField body="body" type="string" required>
    The message. HTML is stored as given. An unsubscribe link is appended by the platform at send time, so do not write one in.
  </ParamField>
  <ParamField body="subject" type="string" required>
    The subject line recipients see in their inbox.
  </ParamField>

### get_newsletter_broadcast

Reads one broadcast, including the message body the merchant wrote. Use it to show a merchant what is about to be sent before calling send_newsletter_broadcast, and to poll sent_count while a send is running.

**Scope:** `read_newsletter`


  <ParamField body="broadcast_id" type="string" required>
    From list_newsletter_broadcasts or create_newsletter_broadcast.
  </ParamField>

### get_newsletter_subscriber_count

Counts the store's newsletter list, optionally for one consent state. This is how many people a broadcast would reach, and it is the only thing this surface says about the list: there is no tool that returns subscriber addresses, because a tool result is read by a model and stored by its host.

**Scope:** `read_newsletter`


  <ParamField body="status" type="string">
    subscribed counts the people a broadcast would actually mail. unsubscribed counts the suppression records. Omit to count every row, which on a double opt-in store also includes addresses that have not confirmed yet and will NOT be mailed.
  </ParamField>

### list_newsletter_broadcasts

Lists this store's newsletter broadcasts, newest first, with each one's id, subject and status. Call this to get the broadcast_id the other newsletter tools need. recipient_count is the snapshot taken when a send started and is 0 on a draft: it is NOT how many subscribers the store has, which is what get_newsletter_subscriber_count answers.

**Scope:** `read_newsletter`


  <ParamField body="after" type="string">
    The cursor printed at the end of a previous page. Pass it back verbatim for the next page; it is not a number and not an id.
  </ParamField>
  <ParamField body="limit" type="integer">
    How many, 1 to 100. Defaults to 20.
  </ParamField>

### send_newsletter_broadcast

Mails a broadcast to every subscribed address in the store. THERE IS NO UNDO AND NO CANCEL: the send starts in the background before this call returns, and what reaches an inbox stays there. Call it with confirm false first, show the merchant how many people it would reach, and pass confirm true only after they have said to.

**Scope:** `write_newsletter:send`


  <ParamField body="broadcast_id" type="string" required>
    From list_newsletter_broadcasts or create_newsletter_broadcast.
  </ParamField>
  <ParamField body="confirm" type="boolean" required>
    False reports what the send WOULD do, how many subscribed addresses it would reach and the subject line, and mails nobody. True mails them. There is no undo: show the merchant the false result and get their word before passing true.
  </ParamField>

## The send scope is separate, and is not requested by default

`write_newsletter` covers drafting. Sending needs `write_newsletter:send` on top of it,
a second grant a merchant ticks separately when minting a key. The split is not
cosmetic: `write_newsletter` is what a storefront signup integration holds to push
addresses onto the list, and every one of those keys was created before this tool
existed. Folding the send into the parent would have handed all of them the ability to
mail the merchant's whole list.

For an OAuth connection, `write_newsletter:send` is **not** part of what discovery
advertises, because nothing qualified ever is: `scopes_supported` is the minimal set for
basic functionality, and a grant that mails a list with no undo is not it. A client that
wants the send asks for it by name, and the merchant approves it on the consent screen
alongside the rest.

Two refusals come from the platform rather than from the broadcast, and both mail nobody:

- **No unsubscribe mechanism.** The store has no configured unsubscribe URL or signing
  key. Mailing without a one-click unsubscribe is a CAN-SPAM / PECR violation, so the
  send is refused rather than sent without one. The merchant fixes this in the store's
  newsletter settings.
- **Email allowance exceeded.** The send would push the store past its plan's monthly
  allowance. The merchant upgrades or waits for the reset.