# send_site_email_bulk

Source: https://modulify.ai/docs/mcp/emails/send-site-email-bulk

Queues one email to many people from a site's own sending address, such as a newsletter or a campaign, each with their own copy and an unsubscribe link.

- Title: Send a bulk email from a site
- Scope: `config:write`
- Access: Destructive

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](https://modulify.ai/docs/built-in/emails#send-a-bulk-email).

It is refused with the same codes as the site's own `/bulk-send`, see [Email HTTP API](https://modulify.ai/docs/built-in/email-http-api#bulk-send), 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 <ana@example.com>", "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. |