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
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
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.
string
required
The subject line recipients see in their inbox.
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
string
required
From list_newsletter_broadcasts or create_newsletter_broadcast.
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
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.
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
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.
integer
How many, 1 to 100. Defaults to 20.
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
string
required
From list_newsletter_broadcasts or create_newsletter_broadcast.
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.
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.