> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send email

> Send transactional or one-off emails to your audience programmatically with POST /newsletters/send.

Send an email to up to **100 recipients** in a single request. Emails are
delivered with your configured sender name, reply-to address, footer, physical
address, and an unsubscribe link — the same conventions as newsletters sent
from the dashboard — and each send is recorded in your account as a sent post
(marked `source: api`) with delivery events and usage tracking.

<Note>
  **Sender verification required.** You must verify your sender email in
  **Newsletters → Settings** before using this endpoint. Unverified senders
  receive a `403` with error code `EMAIL_SENDER_NOT_VERIFIED`.
</Note>

## Endpoint

```
POST https://api.pocketsflow.com/newsletters/send
```

Authenticate with your API key as a Bearer token (`pk_live_…` or `pk_test_…`).
See [API reference](/api-reference/introduction) for how to create a key.

## Request body

| Field      | Type                | Required | Description                                                                     |
| ---------- | ------------------- | -------- | ------------------------------------------------------------------------------- |
| `to`       | string or string\[] | Yes      | A recipient email address, or an array of 1–100 addresses.                      |
| `subject`  | string              | Yes      | Email subject line.                                                             |
| `html`     | string              | Yes\*    | HTML body of the email. \*Required unless `text` is provided.                   |
| `text`     | string              | No       | Plain-text body. If `html` is omitted, a simple HTML body is generated from it. |
| `fromName` | string              | No       | Sender display name. Defaults to your newsletter settings' default from name.   |
| `replyTo`  | string              | No       | Reply-to address. Defaults to your configured reply-to (or sender) email.       |
| `preview`  | string              | No       | Inbox preview text.                                                             |

## Example request

```bash theme={null}
curl https://api.pocketsflow.com/newsletters/send \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your weekly update",
    "html": "<p>Hi there — here is what is new this week.</p>",
    "fromName": "Acme Studio",
    "replyTo": "hello@acme.com"
  }'
```

Send to many recipients at once (max 100), or send a plain-text email:

```bash theme={null}
# Up to 100 recipients in a single call
curl https://api.pocketsflow.com/newsletters/send \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["a@example.com", "b@example.com", "c@example.com"],
    "subject": "Doors are open",
    "text": "The cohort is live — reply if you have any questions.",
    "preview": "Your spot is ready"
  }'
```

## Example response

```json theme={null}
{
  "id": "665f1c2e8b3735856be339aa",
  "accepted": ["customer@example.com"],
  "status": "sent"
}
```

| Field      | Description                                        |
| ---------- | -------------------------------------------------- |
| `id`       | ID of the email post recorded for this send.       |
| `accepted` | The recipients the email was successfully sent to. |
| `status`   | Always `"sent"` on success.                        |

## Errors

| Status | Error                       | Meaning                                                                                                                |
| ------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `400`  | message in `error`          | Validation failed — invalid recipient, more than 100 recipients, missing `subject`, or missing both `html` and `text`. |
| `401`  | —                           | Missing or invalid API key.                                                                                            |
| `403`  | `EMAIL_SENDER_NOT_VERIFIED` | Your sender email is not verified yet.                                                                                 |
| `502`  | `EMAIL_SEND_FAILED`         | No emails could be delivered. Retry later.                                                                             |

## Behavior & limits

* **Recipients:** provide a single address or an array of **1–100**. Addresses
  are normalized to lowercase and de-duplicated before sending. More than 100
  returns `400`.
* **Body:** provide `html`, `text`, or both. If only `text` is given, a simple
  HTML body is generated from it; `text` is always used as the plain-text
  alternative for better deliverability.
* **Sender identity:** `fromName` and `replyTo` default to your Newsletter
  settings when omitted. The sending address must be a **verified** sender.
* **Compliance:** every email automatically includes your footer, physical
  address, and a per-recipient unsubscribe link — you don't add these yourself.
* **Recording & usage:** each send is stored as a post (`source: api`) and counts
  toward your email usage (`totalEmailsSent`).
* **Idempotency:** the endpoint does not de-duplicate across separate calls —
  guard against accidental double-sends on your side (for example, key retries
  on your own request id).

## Notes

* This endpoint shares the `/newsletters` surface; to publish a full newsletter
  post to all subscribers instead, use
  [`POST /newsletters/posts/{id}/send`](/api-reference/introduction#newsletters).
* The full OpenAPI definition is available in the
  [interactive API reference](https://api.pocketsflow.com/docs).

## Related topics

* [API reference](/api-reference/introduction)
* [MCP server](/api-reference/mcp-server) — call this as the `send_email` tool.