---
title: Emails
description: Send one email or a batch, schedule it, and follow it from accepted to delivered.
---

An email is one `POST /emails` request, or one message over the [SMTP relay](/docs/smtp). BillionSend checks it, stores it and returns an `id` right away. The sending happens in the background, so a `200` means the email is accepted, not delivered.

## Send an email

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send({
  from: "Acme <hello@mail.example.com>",
  to: ["user@example.org"],
  subject: "Welcome",
  html: "<p>Thanks for signing up.</p>",
});
```

The same call with `curl`:

```bash
curl -X POST https://api.billionsend.com/emails \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.example.com>",
    "to": ["user@example.org"],
    "subject": "Welcome",
    "html": "<p>Thanks for signing up.</p>"
  }'
```

- `from`: must be on a [verified domain](/docs/concepts/domains) of your team.
- `to`, `cc`, `bcc`, `reply_to`: an address or a list. `to`, `cc` and `bcc` together hold at most 50 recipients.
- `html` and `text`: at least one is required. Sending with a template id is not supported. A [template](/docs/concepts/templates) is content you copy into a broadcast.
- `tags`, `headers`, `attachments`: see [API basics](/docs/api-reference/basics) for the rules, the attachment limits and idempotency.
- `topic_id`: recipients who opted out of that [topic](/docs/concepts/topics) are skipped.

To test without emailing anyone, send to `success@simulator.amazonses.com`.

## Send a batch

`POST /emails/batch` takes an array of up to 100 emails. By default one invalid email fails the whole batch. Add the header `x-batch-validation: permissive` to accept the valid ones: `data` lists their ids, and `errors` lists the others by position.

## Schedule, change, cancel

Add `scheduled_at` to send later, up to 30 days ahead. It takes an ISO 8601 time with an offset, or a relative time such as `in 2 hours`. While an email is scheduled, `PATCH /emails/{id}` changes its time and `POST /emails/{id}/cancel` cancels it.

## Follow an email

`GET /emails/{id}` returns the email with `last_event`, its newest outcome, and a `score` from [Deliverability Insights](/docs/concepts/deliverability-insights). In the dashboard, **Emails** lists every email and shows its events in order. Bodies and history are kept for 30 days.

| Event | Meaning |
| --- | --- |
| `email.scheduled` | Accepted, and waiting for its time. |
| `email.sent` | Handed over for delivery. |
| `email.delivered` | The recipient's server accepted it. |
| `email.delivery_delayed` | Delivery is delayed and will be retried. |
| `email.bounced` | The recipient's server refused it. |
| `email.complained` | The recipient marked it as spam. |
| `email.failed` | It could not be sent. The event says why. |
| `email.suppressed` | It was not sent because every recipient is suppressed or unsubscribed. |
| `email.opened`, `email.clicked` | The recipient opened it or clicked a link, if [tracking](/docs/concepts/tracking) is on. |

Each event can also be sent to you as a [webhook](/docs/concepts/webhooks).

## What stops or holds a send

A send is refused with a `4xx` error that names the reason when:

- the sender domain is not verified (`422`);
- every recipient is [suppressed](/docs/concepts/suppressions) (`422 all_recipients_suppressed`);
- you are past your plan's volume (`429`);
- your bounce or complaint rate has paused sending (`403 sending_paused`).

Some mail is accepted but held, and goes out later: a new domain over its daily cap, or mail waiting for a limit to reset. See [Sending limits](/docs/concepts/sending-limits). The API and the SMTP relay apply the same rules.
