send_site_email_bulk

The answer comes back as soon as the email is queued, and it goes out in the background at up to 300 recipients a minute. Each recipient gets a separate email with their own delivery status, opens and clicks. A site can have 5 bulk emails running at once and can queue 60 in an hour.

The tool tells the client to use it only when you ask for this mail to be sent and say who gets it, to show you the subject, the text, how many people it goes to and any credits it may cost first, and never to use addresses that were scraped, bought or rented. An email that went out cannot be taken back.

Every recipient who gets it is one send of the site's monthly allowance. Past that allowance a paid plan buys further blocks with credits as it goes, and pauses with none left, while a free plan refuses a list longer than the sends it has left.

By default every email gets an unsubscribe link and the one-click unsubscribe headers, and an address that unsubscribed is skipped. Put {{unsubscribeUrl}} in the html and the text to choose where the link goes, or a short line is added at the end of each body without it. In subject, html and text, {{email}}, {{name}} and any field of a recipient's data are filled in for that person, values in html are escaped, and {{name|there}} gives a fallback. A recipient whose filled-in subject or body breaks a limit is marked failed, and everyone else still gets the email.

The answer carries the id, the status, the total, accepted, suppressed and duplicates counts, the addresses that were not valid in invalid with invalidCount, and extraBlocks and extraCredits, the extra blocks and credits it may buy. Follow it with get_site_email_bulk and stop it with cancel_site_email_bulk. See Send a bulk email.

It is refused with the same codes as the site's own /bulk-send, see Email HTTP API, and also with 409 and the code secret-conflict while the site's own EMAIL_URL or EMAIL_PRIVATE_KEY secret keeps its email off. A list longer than 10,000 is refused, never split, so send several bulk emails.

Inputs

Input	Type	Required	Description
projectId	string	Yes	The site id.
recipients	array of objects	Yes	Who gets the email, at most 10,000, each an object such as { "to": "Ana <[email protected]>", "data": { "plan": "Pro" } }. to is one email address, where Name <address> works too, and the optional data holds details for that person under names that start with a letter and use only letters, digits and underscores, at most 2 KB. A repeated address gets one email, and an address that is not valid is left out and listed in the answer.
subject	string	Yes	The subject line, at most 300 characters, with no line breaks.
html	string	No	The HTML body, at most 400,000 characters, with no script tag. At least one of html and text is required.
text	string	No	The plain text body, at most 400,000 characters, best sent alongside html.
replyTo	string or array of strings	No	Where replies go: one address, or a list of up to 10, where Name <address> works too. Without it, replies go to the site's own reply-to address, or else to its sending address.
fromName	string	No	The sender name for this bulk email, instead of the site's own sender name, at most 64 characters.
headers	object	No	Custom headers as an object of names and values: at most 10 X- headers, plus List-Unsubscribe and List-Unsubscribe-Post, each value printable ASCII with no line breaks, on every email. Your own List-Unsubscribe headers are refused unless unsubscribe is false.
tags	array of objects	No	Labels stored with every email, at most 10, each with a name and a value of letters, digits, dashes and underscores. project, send and forward are reserved names.
unsubscribe	boolean	No	False for mail people need rather than marketing, such as a service notice. It leaves out the unsubscribe link and also reaches addresses that unsubscribed. Defaults to true.
idempotencyKey	string	No	A unique key for this bulk email, such as newsletter-2026-11, so a retry never queues it twice. At most 256 characters.