# Send an email, a batch, or one for later

> `POST /v1/emails` takes one email and answers with its id; everything after it is on the email's page.

Canonical: https://minket.com/sending. Updated: 2026-10-28.

*One request and the row it becomes.* A send with a stored attachment and a tag, and the emails list in the console with that email selected, queued.

## Retry with the same key and get the same answer

An idempotency key holds for 24 hours, and the TypeScript SDK puts one on every send that has none.

**A request sent again**

- Same key, same body: the stored answer, `idempotent_replay: true`
- Same key, other body: `422 invalid_idempotent_request`
- Same key, still running: `409 concurrent_idempotent_requests`

## A batch of 100, one answer each

`POST /v1/emails/batch` checks every item on its own, so one bad address costs one email.

**The answer to a batch of two**

```json
{
  "object": "batch",
  "data": [
    {
      "index": 0,
      "id": "019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5d",
      "status": "queued"
    },
    {
      "index": 1,
      "error": { "code": "validation_error", "retryable": false }
    }
  ],
  "accepted": 1,
  "rejected": 1
}
```

## Schedule up to 30 days ahead

Set `scheduled_at` to a time or to words read in UTC, then move or cancel it until it goes.

**Scheduled in words**

```json
{ "scheduled_at": "tomorrow at 9am" }
```

## Attachments inline, by reference or by URL

Up to 20 on one email, within 40 MB for the whole message.

**Three ways to attach a file**

| Form | Up to | How |
| --- | --- | --- |
| Inline | 4 MB | `content` in the request |
| By reference | 25 MB | an `id` from `POST /v1/attachments`, reused |
| By URL | 25 MB | `path`, fetched over https as it sends |

## No email goes out twice

When a send's outcome is unclear, the email is marked failed with `outcome_unknown` instead of going out again.

**What a status means**

- sent: accepted for delivery
- delivered: the receiving server took it
- failed: with a reason you can act on

## Test keys deliver nothing

A `minket_test_` key accepts, renders and stores mail and plays its events, 2 seconds apart.

*The sandbox page of the console.* Test mode under its overprint, with the events each recipient at minket.test plays.

## Templates, streams and SMTP

- **[Templates](https://docs.minket.com/templates/)**: Hosted and versioned, the last 50 versions kept.
- **[Streams](https://docs.minket.com/sending/)**: Transactional and marketing mail apart; marketing carries an unsubscribe link.
- **[SMTP](https://docs.minket.com/smtp/)**: Credentials for software that only speaks SMTP.
- **Automatic pause**: Live sending stops when bounces or complaints climb, until you resume it; waiting mail stays put.

## Questions

### What if an address is suppressed?

The email is accepted and reported with `email.suppressed`, and the other recipients still get it.

### Can marketing mail go to many?

One recipient per marketing email, so each unsubscribe link belongs to one person.

### How many recipients per email?

Up to 50 across `to`, `cc` and `bcc`.

More: Read the sending guide, https://docs.minket.com/sending/