# Emails

Send transactional email and list recent sends. Migrating from Resend? See [Migration from Resend](https://docs.groundmail.dev/migration).

---

## Send email

`POST /emails`

Send a transactional email from a verified domain.

Base URL: `https://api.groundmail.dev`

<!-- tabs -->

```bash cURL
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reset-8841" \
  -d '{
    "from": "Acme <hello@mail.acme.io>",
    "to": "maya@northwind.io",
    "subject": "Reset your password",
    "html": "<p>Your code is 482913</p>"
  }'
```

```ts Node.js
import { Groundmail } from 'groundmail'

const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY!)

const { id, status } = await groundmail.emails.send({
  from: 'Acme <hello@mail.acme.io>',
  to: 'maya@northwind.io',
  subject: 'Reset your password',
  html: '<p>Your code is 482913</p>',
  idempotencyKey: 'reset-8841',
})
```

```python Python
import os

from groundmail import Groundmail

groundmail = Groundmail(os.environ["GROUNDMAIL_API_KEY"])

result = groundmail.emails.send(
    from_="Acme <hello@mail.acme.io>",
    to="maya@northwind.io",
    subject="Reset your password",
    html="<p>Your code is 482913</p>",
)
```

```go Go
client, err := groundmail.New(os.Getenv("GROUNDMAIL_API_KEY"))
if err != nil {
	log.Fatal(err)
}

result, err := client.Emails.Send(map[string]any{
	"from":    "Acme <hello@mail.acme.io>",
	"to":      "maya@northwind.io",
	"subject": "Reset your password",
	"html":    "<p>Your code is 482913</p>",
})
```

<!-- /tabs -->

<!-- tabs -->

```json 200
{
  "id": "msg_794399cdfb1bfc21",
  "status": "queued"
}
```

```json 422
{
  "error": {
    "message": "One or more recipients are suppressed",
    "code": "validation_error",
    "hint": "…",
    "docs_url": "https://docs.groundmail.dev/errors#validation_error",
    "details": { "suppressed": ["maya@northwind.io"] }
  }
}
```

```json 429
{
  "error": {
    "code": "plan_limit",
    "message": "…",
    "hint": "…",
    "docs_url": "https://docs.groundmail.dev/errors#plan_limit",
    "upgrade_url": "/settings/billing"
  }
}
```

<!-- /tabs -->

---

## Authentication

```http
Authorization: Bearer gm_…
```

API keys are created in the dashboard (**API Keys**). Keys start with `gm_`.

---

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | `string` or `{ email, name? }` | Yes* | Exactly one address, on a verified domain: `you@yourdomain.com`, `Name <you@yourdomain.com>` or `{ email, name }`. Put a name with special characters in double quotes (`"Acme: Support" <you@yourdomain.com>`), or use `{ email, name }`. Optional when you pass `sender`, the template has a sender, or your team has a default sender ([who it's from](#who-its-from)). When set, it wins. |
| `sender` | `string` | No | A saved [sender](https://docs.groundmail.dev/senders)'s handle or id, such as `"billing"`. Sets `from`, and `reply_to` when you don't pass one. Ignored when `from` is set. An unknown sender returns `422`. |
| `to` | `string` or `string[]` | Yes | Recipient(s), each `ada@example.com`, `Ada <ada@example.com>` or `"Lovelace, Ada" <ada@example.com>`. Pass several as an array: each entry is exactly one address. |
| `subject` | `string` | Yes | Subject line |
| `html` | `string` | No* | HTML body (`htmlBody` / `html_body` aliases accepted) |
| `text` | `string` | No* | Plain-text body (`textBody`, `text_body`, and `plain_body` aliases accepted) |
| `reply_to` | `string` or `string[]` | No | Reply-to address(es) (`replyTo` alias accepted) |
| `cc` | `string` or `string[]` | No | CC recipient(s), written like `to` |
| `bcc` | `string` or `string[]` | No | BCC recipient(s), written like `to` |
| `tags` | `{ name, value }[]` or object | No | Up to 10 key/value tags stored with the email |
| `headers` | `object` | No | Custom headers; dangerous transport headers are rejected |
| `attachments` | `array` | No | Up to 10 files, 10MB decoded each, in a request of at most 20MB ([limits](#attachment-limits)); executable/script extensions are blocked. Attachment aliases `filename`, `contentType`, `content`, and `contentId` are also accepted. |
| `scheduled_at` | `string` | No | ISO 8601 timestamp. Creates a scheduled email instead of sending immediately (`scheduledAt` alias accepted) |
| `unsubscribe` | `boolean` | No | Opt in to managed unsubscribe (see below). Off by default for transactional mail. |
| `validation` | `object` | No | Opt-in checks for this send. `{ "block_bot_signups": true }` holds back addresses that look like bot sign-ups ([details](https://docs.groundmail.dev/validation#bot-sign-ups)). Off by default. |
| `category` | `string` | No | **Deprecated.** Groundmail decides whether each email is transactional or product ([how](https://docs.groundmail.dev/deliverability#detected-category)), so `transactional` and `product` are accepted and ignored. `newsletter` still sends an opt-in newsletter, for approved accounts: see [Newsletter category](#newsletter-category-by-approval). |
| `tenant` | `string` | No | Send as one of your [tenants](https://docs.groundmail.dev/tenants) (its `external_id` or `id`): the send uses that tenant's domains, suppression list, sending ramp and pause switch. A send from a tenant's own domain is that tenant's without it. Pay as you go and Dedicated plans; on Free it returns `403` `tenants_not_enabled`. |

\* At least one of `html` or `text` is required. `from` is required only when nothing else says who the email is from (below).

### Who it's from

Groundmail picks the From address in this order:

1. `from` (and `reply_to`) on the request.
2. `sender` on the request: a saved sender's name, address and reply-to.
3. The template's sender, when you send a template that has one.
4. Your team's default sender.

With none of these, the send returns `400` asking for `from`. Add and manage senders under **Domains › Senders** in the dashboard, or with the [Senders API](https://docs.groundmail.dev/senders).

```json
{
  "sender": "billing",
  "to": "user@example.com",
  "template": { "id": "receipt", "variables": { "amount": "$20.00" } }
}
```

Addresses with an internationalized domain (`info@bücher.example`) can be sent in either form: Groundmail converts the domain to its ASCII (punycode) form, `info@xn--bcher-kva.example`, before sending. The email record and webhooks show the converted address.

### Managed unsubscribe (opt-in)

Pure transactional mail (password resets, receipts, security alerts) should leave `unsubscribe` off.

When `unsubscribe: true`, Groundmail:

- Injects RFC 8058 `List-Unsubscribe` and `List-Unsubscribe-Post` headers (one-click unsubscribe)
- Replaces `{{unsubscribe_url}}` in `subject`, `html`, and `text` with a signed confirmation link
- Binds the link to the first `to` address for that message

When sending with a published template, the template's `unsubscribe_enabled` flag is used unless you pass `unsubscribe` explicitly on the send request. Product templates auto-enable managed unsubscribe and support category-scoped opt-out — recipients can unsubscribe from product email without blocking transactional mail.

### Template categories

Groundmail decides each template's category from its published content, and sends from it go out by that:

| Category | Unsubscribe behavior | Sent from |
|----------|---------------------|-----------|
| `transactional` | No category opt-out. Global suppression only. | Transactional IPs |
| `product` | Category-scoped opt-out, with managed unsubscribe | Product IPs |

A template's own `category` field is deprecated: it's stored and ignored. Templates and automation steps still reject `newsletter` with a `400` `validation_error`. See [Transactional and product streams](https://docs.groundmail.dev/deliverability#transactional-and-product-streams).

### Newsletter category (by approval)

`category: "newsletter"` on `POST /emails` (or an item of `POST /emails/batch`) sends an opt-in newsletter. It is accepted only for accounts we approve; email support@groundmail.dev to ask. Approved newsletter email:

- goes out from its own IPs, separate from transactional and product email, so a newsletter can never affect your sign-in codes and receipts;
- always carries `List-Unsubscribe` and one-click unsubscribe (`List-Unsubscribe-Post`), and `{{unsubscribe_url}}` is filled in; `unsubscribe: false` is a `400` `validation_error`;
- honours category opt-outs (a recipient can leave your newsletter and keep getting transactional and product email), suppressions and Groundmail validation like product email;
- has its own daily [ramp-up limit](https://docs.groundmail.dev/sending-limits#new-account-ramp-up), the same size as the product limit and counted separately;
- is paused on its own after high bounce or complaint rates, leaving transactional and product email sending.

On an account that is not approved, the send returns `403` and nothing is sent. Groundmail never sends it as another category instead:

```json
{
  "error": {
    "message": "Newsletter sending isn't enabled on this account yet. Newsletter email is accepted only for approved accounts.",
    "code": "newsletter_not_enabled",
    "hint": "Send transactional or product email as usual. To send opt-in newsletters, email support@groundmail.dev to ask for approval; until then, `category: \"newsletter\"` sends are refused and nothing is sent.",
    "docs_url": "https://docs.groundmail.dev/errors#newsletter_not_enabled"
  }
}
```

Each email's `stream` (`transactional`, `product` or `newsletter`) and its [`detected_category`](https://docs.groundmail.dev/deliverability#detected-category) are on [`GET /emails`](#list-emails), [`GET /emails/{id}`](#retrieve-email) and webhook payloads; `stream` is also in the dashboard's Emails list.

Sends to recipients who opted out of a category return `422`. A send for a [tenant](https://docs.groundmail.dev/tenants) checks that tenant's opt-outs and the account-wide ones; an opt-out from one tenant's email never blocks another tenant's:

```json
{
  "error": {
    "message": "One or more recipients opted out of this email category",
    "code": "validation_error",
    "details": {
      "category_unsubscribed": ["user@example.com"],
      "category": "product",
      "email_id": "msg_…"
    }
  }
}
```

To let a recipient who re-subscribed receive that category again, remove the opt-out: see [Category opt-outs](https://docs.groundmail.dev/suppressions#category-opt-outs).

Global suppressions return the same status with `details.suppressed` instead.

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Product updates",
  "html": "<p>Hi there.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
  "unsubscribe": true
}
```

### Example

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello from Groundmail",
  "html": "<p>It works.</p>"
}
```

With display name:

```json
{
  "from": { "email": "you@yourdomain.com", "name": "Your App" },
  "to": ["user@example.com", "other@example.com"],
  "subject": "Hello",
  "html": "<p>Hi</p>",
  "text": "Hi",
  "reply_to": ["support@yourdomain.com"],
  "tags": [{ "name": "order_id", "value": "ord_123" }],
  "headers": { "X-Entity-ID": "ord_123" }
}
```

### Sandbox self-test

Before your own domain is verified, you can self-test with the shared sandbox domain:

```json
{
  "from": "noreply@mail.groundmail.dev",
  "to": "owner@example.com",
  "subject": "Sandbox check",
  "html": "<p>Sandbox works.</p>"
}
```

The sandbox sender is limited to the account email attached to the API key owner.

After your domain is verified, you can also self-test **from your verified domain** on the free plan — still limited to the account email:

```json
{
  "from": "you@yourdomain.com",
  "to": "owner@example.com",
  "subject": "Verified domain check",
  "html": "<p>My domain works.</p>"
}
```

Add a payment method to unlock Free production (send to other recipients on your verified domain). Free is never charged; you're only billed if you turn on pay as you go. Turn on pay as you go at Settings → Billing to keep sending past 3,000 a month.

---

## Responses

### 200 — Accepted

```json
{
  "id": "msg_abc123…",
  "status": "queued"
}
```

Groundmail answers as soon as your email is checked and safely stored, and hands it to the mail server in the background, so the call doesn't wait for that hand-off. `status: "queued"` means exactly that: the email is accepted and on its way. Follow what happens next with [`GET /emails/{id}`](#retrieve-email) or [webhooks](https://docs.groundmail.dev/webhooks):

- `email.delivered` when the recipient's mail server accepts it;
- `status: "failed"` with a `bounce_reason`, and an `email.failed` webhook, if the mail server refuses it. A refusal like that used to come back as an `upstream_error` on the send call; for a `queued` send it arrives this way instead;
- temporary mail server problems are retried for you for about 15 minutes before an email is marked `failed`.

An email with attachments is handed to the mail server during the request, so its response comes back once the mail server has it, and a mail server problem is an [`upstream_error`](https://docs.groundmail.dev/errors#upstream_error) on the call.

Scheduled sends return:

```json
{
  "id": "msg_abc123…",
  "status": "scheduled"
}
```

`id` is a stable public message ID (`msg_…`). Use it to correlate webhook events and dashboard activity.

A test send (a test key, `gm_test_…`, or only [simulator addresses](https://docs.groundmail.dev/testing#simulator-addresses)) adds `"test": true`. Nothing was delivered: its status and webhooks are simulated. See [Testing](https://docs.groundmail.dev/testing).

### Recipients held back by Groundmail validation

Before an email goes out, Groundmail validation holds back recipients that cannot receive email, so they never bounce. This is on for every account and costs nothing. A recipient is held back when:

| `reason` | Meaning |
|----------|---------|
| `invalid_address` | The address cannot exist (for example `ada@@example.com`). |
| `no_mail_server` | The domain does not exist or takes no email: no MX or A record, or a null MX. |
| `previously_bounced` | The address hard-bounced (the mailbox does not exist) for a Groundmail sender in the last 90 days. |
| `mailbox_not_found` | Groundmail validation already knows the mailbox does not exist. |
| `likely_bot_signup` | The address looks like a bot filled it into a form. Only when the send sets `validation: { "block_bot_signups": true }`; see [Bot sign-ups](https://docs.groundmail.dev/validation#bot-sign-ups). |

Disposable and role addresses (`info@`, `support@`) are never held back: they can receive email, and whether to accept them is your call. Check them up front with [`POST /validate`](https://docs.groundmail.dev/validation). Unless a send opts in to `block_bot_signups`, nothing that is merely uncertain is held back, and the check never slows a send down.

When some recipients are held back, the email goes to the rest and the response lists who was held back and why:

```json
{
  "id": "msg_abc123…",
  "status": "queued",
  "held_back": [{ "email": "ada@no-mail.example", "reason": "no_mail_server" }]
}
```

When every `to` recipient is held back, nothing is sent. The API returns **422** with `code: validation_error` and `details.held_back`, a `suppressed` email record is created, and `email.suppressed` fires with `held_back` in its data, the same as for a suppressed recipient:

```json
{
  "error": {
    "message": "Groundmail validation held back every recipient",
    "code": "validation_error",
    "details": {
      "held_back": [{ "email": "ada@no-mail.example", "reason": "no_mail_server" }],
      "email_id": "msg_…"
    }
  }
}
```

The email object (`GET /emails/{id}`) carries `held_back` too, and the dashboard's Emails page shows it. `previously_bounced` and `mailbox_not_found` draw on what Groundmail has seen across senders; an account owner can turn those two off in **Settings → Suppressions**. `invalid_address` and `no_mail_server` always apply.

---

## Idempotency

Optional header on `POST /emails` and [`POST /emails/batch`](#batch-send):

```http
Idempotency-Key: order-123
```

Keys are scoped per account, retained for **24 hours**. Replays return the original response and send nothing again. For a send answered `queued`, the replay is that same `queued` response even after the email has gone out: read its current status with [`GET /emails/{id}`](#retrieve-email). Reusing a key with a different body returns **409** `idempotency_conflict`. Keys used with a test key are kept apart from keys used with live keys, and batch keys from single-send keys.

```ts
await client.emails.send({ …, idempotencyKey: 'order-123' })
await client.emails.batch([…], { idempotencyKey: 'digest-2026-11-02' })
```

---

## Retrieve email

`GET /emails/{id}`

Returns one send by public id (`msg_…`).

```ts
const { email } = await client.emails.get('msg_abc123…')
```

Emails older than your plan's [data retention](#data-retention) window return the normal `404 not_found`.

### Delivery details

`delivery` shows what the recipient's mail server said about the latest delivery attempt: which server took the email, its exact reply, and whether the connection used TLS.

```json
{
  "email": {
    "id": "msg_abc123…",
    "status": "delivered",
    "created_at": "2026-10-29T12:00:00.000Z",
    "delivered_at": "2026-10-29T12:00:02.900Z",
    "delivery": {
      "receiving_server": "gmail-smtp-in.l.google.com",
      "response": "250 2.0.0 OK  1793012345 d75a77b69052e-4613a1b2c3si123456a.42 - gsmtp",
      "tls": true,
      "deferred_response": null,
      "deferred_at": null
    }
  }
}
```

| Field | Meaning |
|-------|---------|
| `receiving_server` | Hostname of the recipient's mail server that took the connection |
| `response` | Its SMTP reply to the latest attempt that finished, exactly as sent: a `250` when it accepted the email, the `5xx` it refused with when it bounced. A multi-line reply is joined into one line. `null` while there has been none |
| `tls` | Whether the connection used TLS. `null` when the attempt didn't say |
| `deferred_response` | Its reply to the latest deferral: a `4xx`, such as greylisting or a rate limit. Delivery is retried automatically, and the deferral stays here after the email is delivered |
| `deferred_at` | When the latest deferral happened |

`delivered_at` minus `created_at` is how long the email took to land, measured from when the API accepted it to when the recipient's server replied `250`.

`delivery` is `null` until an attempt reports one, for test emails, and for emails sent before 29 October 2026. List rows (`GET /emails`) carry it too.

To watch an email land from the terminal, live, with the server's reply and the time: `groundmail emails send … --watch`, or `groundmail emails get <id> --watch` for one you already sent. See [Watch an email land](https://docs.groundmail.dev/cli#watch-an-email-land).

---

## Data retention

Groundmail keeps your email logs for a set number of days by plan, then deletes them.

| Plan | Logs kept |
|------|-----------|
| Free | 7 days |
| Pay as you go | 90 days |
| Dedicated | Up to 1 year, set for your account |

**Deleted after the window:** each sent email's content (subject, HTML and text bodies, headers, attachment details) and its delivery and engagement events (delivered, bounced, complained, opened, clicked), and inbound emails you received (`GET /received-emails`). Once deleted, `GET /emails/{id}` and `GET /received-emails/{id}` return `404 not_found`, and the email no longer appears in lists, search, exports or the dashboard.

**Kept:** aggregate sending stats (sent, delivered, bounce and complaint counts and rates on Home, the Emails page and `GET /deliverability`), suppressions, templates, domains and everything else in your account.

The window counts from when the email was created. Scheduled emails are kept until they send.

**Keeping history longer:** subscribe a [webhook](https://docs.groundmail.dev/webhooks) to the `email.*` and `email.received` events and store each one in your own database. Webhooks deliver every event as it happens, so your copy has no time limit. Turning on pay as you go extends the window for emails that haven't been deleted yet.

---

## Resend

`POST /emails/{id}/resend`

Creates a **new** send from a previously stored email (same from/to/subject/body, tags, and headers). Returns a new `msg_…` id. Attachment bytes are not stored, so attachments are omitted.

Dashboard: Emails → **Resend** on any row.

SDK:

```ts
await client.emails.resend('msg_abc123…')
```

CLI:

```bash
groundmail emails resend --id msg_abc123…
```

---

## Schedule, reschedule, and cancel

Add `scheduled_at` to `POST /emails` to store the message and enqueue it for later delivery:

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Tomorrow",
  "html": "<p>See you tomorrow.</p>",
  "scheduled_at": "2026-08-01T12:00:00.000Z"
}
```

Scheduled emails can be updated only while their status is `scheduled`:

```http
PATCH /emails/msg_abc123…
```

```json
{ "scheduled_at": "2026-08-01T13:00:00.000Z" }
```

Cancel a scheduled email:

```json
{ "cancel": true }
```

Suppressions and category unsubscribes are checked again when a scheduled email goes out. If a recipient was suppressed or opted out of the email's category since you scheduled it, the email isn't sent: its status becomes `suppressed`, with the reason in `bounce_reason`, and you get an `email.suppressed` webhook.

SDK:

```ts
await client.emails.update('msg_abc123…', { scheduledAt: '2026-08-01T13:00:00.000Z' })
await client.emails.cancel('msg_abc123…')
```

CLI:

```bash
groundmail emails cancel --id msg_abc123…
```

Scheduled a whole [batch](#batch-send)? Cancel every email in it that hasn't gone out yet in one call with [`POST /batches/{id}/cancel`](#batches).

Scheduled sends store message bodies so the worker can send them later. Attachments are not supported on scheduled emails in v1 because raw attachment data is not stored.

---

## Batch send

`POST /emails/batch`

Send up to 100 emails in one request:

```json
{
  "emails": [
    {
      "from": "you@yourdomain.com",
      "to": "user@example.com",
      "subject": "Hello",
      "html": "<p>Hi</p>"
    }
  ]
}
```

The response is index-aligned, with a `batch_id` shared by every email the call accepted:

```json
{
  "batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
  "data": [
    { "index": 0, "id": "msg_abc123…", "status": "queued" }
  ]
}
```

Each of those emails also carries the id as `batch_id` in [`GET /emails/{id}`](#retrieve-email) and [`GET /emails`](#list-emails). Use it to [check on or cancel the batch](#batches).

Each item is stored and handed to the mail server in the background, like a [single send](#responses), so a batch answers quickly: a mail server refusal arrives as `email.failed` rather than in the item. Each item can name its own `tenant`. Per-email validation failures are returned in that item’s `error`. An item whose email went out with some recipients held back by [Groundmail validation](#recipients-held-back-by-groundmail-validation) carries `held_back`; one with every recipient held back has a `validation_error` with `details.held_back`. Attachments are rejected for batch sends in v1.

Send limits are checked for each email in order. If a batch is bigger than what is left of today’s limit, the emails that fit are sent and the rest come back with an error in their item: `plan_limit` for the Free plan’s 100 a day, `daily_ramp_limit` for a new account’s [ramp-up limit](https://docs.groundmail.dev/sending-limits#new-account-ramp-up).

Each email in a batch counts toward the account's [request rate](https://docs.groundmail.dev/sending-limits), as that many `POST /emails` would. A batch that doesn't fit right now is refused whole with **429** `rate_limited` and a `Retry-After`; nothing in it is sent. A batch with more emails than the per-minute rate is refused the same way without `Retry-After`: split it.

An `Idempotency-Key` header covers the whole batch, with the same rules as [single sends](#idempotency). If no email in the batch was accepted or stored, the key is released so a corrected retry can use it.

SDK:

```ts
const result = await client.emails.batch([{ from, to, subject, html }], { idempotencyKey: 'digest-2026-11-02' })
result.batch_id // 'batch_3f9a…'
```

---

## Batches

A batch is the emails one `POST /emails/batch` call accepted. Schedule one by giving each email a `scheduled_at`, then check on it or call it off with its `batch_id`. A [tenant-scoped key](https://docs.groundmail.dev/tenants) sees and cancels only its tenant's emails in a batch.

### Get a batch

`GET /batches/{id}` (scope `emails:read`)

```json
{
  "batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
  "created_at": "2026-11-03T09:00:00.000Z",
  "total": 100,
  "counts": { "scheduled": 98, "sent": 2 }
}
```

`counts` has a key for each status with at least one email. For the emails themselves, use [`GET /emails/{id}`](#retrieve-email) with the ids from the batch response.

### Cancel a batch

`POST /batches/{id}/cancel` (scope `emails:send`)

Cancels every email in the batch that is still `scheduled`, the same way [cancelling one](#schedule-reschedule-and-cancel) does: its status becomes `cancelled` and `cancelled_at` is set. Emails already queued, sent or finished are left alone.

```json
{
  "batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
  "cancelled": 98,
  "already_cancelled": 0,
  "not_cancellable": 2
}
```

It's safe to repeat: a second call cancels nothing more and counts the earlier ones in `already_cancelled`. Both endpoints return **404** `not_found` for a batch id that isn't on your account, and once every email in the batch is past your plan's [log retention](#data-retention).

SDK:

```ts
const { batch_id } = await client.emails.batch(emails) // each with scheduledAt
await client.batches.get(batch_id)
await client.batches.cancel(batch_id)
```

CLI:

```bash
groundmail batches get batch_3f9a…
groundmail batches cancel batch_3f9a…
```

MCP: `get_batch` and `cancel_batch`.

---

## List emails

`GET /emails?limit=25&cursor=…`

Returns recent sends for the authenticated API key’s account. `limit` is 1–100 (default 25). Use opaque `cursor` / `next_cursor` for pagination. `test=true` lists only test emails, `test=false` only live ones. `tenant=cust_8412` lists one [tenant](https://docs.groundmail.dev/tenants)'s emails; a key limited to one tenant only ever sees its tenant's. `stream=transactional|product|newsletter` lists one mail stream's emails.

Responses include rate-limit headers for the monthly quota: `ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`. When a daily limit applies (Free's 100 a day, or a new account's ramp-up limit for the email's stream, counted in recipients), they also include `ratelimit-daily-limit`, `ratelimit-daily-remaining` and `ratelimit-daily-reset`.

### 200

```json
{
  "emails": [
    {
      "id": "msg_abc123…",
      "from": "you@yourdomain.com",
      "to": ["user@example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "subject": "Hello",
      "status": "delivered",
      "last_event": "delivered",
      "bounce_reason": null,
      "bounce_type": null,
      "delivery": {
        "receiving_server": "mx.example.com",
        "response": "250 2.0.0 Ok: queued as 4F2B1C",
        "tls": true,
        "deferred_response": null,
        "deferred_at": null
      },
      "held_back": [],
      "test": false,
      "stream": "transactional",
      "detected_category": "transactional",
      "tags": [],
      "batch_id": null,
      "scheduled_at": null,
      "cancelled_at": null,
      "created_at": "2026-07-25T12:00:00.000Z",
      "sent_at": "2026-07-25T12:00:01.000Z",
      "delivered_at": "2026-07-25T12:00:05.000Z",
      "bounced_at": null,
      "opened_at": null,
      "clicked_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Status values: `queued`, `scheduled`, `sent`, `delivered`, `delayed`, `opened`, `clicked`, `bounced`, `complained`, `failed`, `suppressed`, `cancelled`.

`test` is `true` for an email that never reached the mail server: sent with a test key or only to simulator addresses. See [Testing](https://docs.groundmail.dev/testing).

`stream` is the mail stream the email went out on, from its `category`: `transactional`, `product` or `newsletter`. Each stream sends from its own IPs.

`detected_category` is what Groundmail decided the email is from its content: `transactional` or `product`. It's `null` while the email is being checked, when its template's category wasn't settled yet when it was sent (a new template, or one just published), and for email Groundmail doesn't check: newsletter sends, test sends, agent mailboxes and forwarded mail. An email's category is set once and doesn't change later. `stream` is what the email went out on. See [Detected category](https://docs.groundmail.dev/deliverability#detected-category).

An email sent for a [tenant](https://docs.groundmail.dev/tenants) also carries `"tenant": "cust_8412"` (the tenant's `external_id`). Account-level emails have no `tenant` field.

`bounce_type` says why an email bounced, and is `null` until it does:

| `bounce_type` | Meaning | Recipient suppressed? |
|---------------|---------|-----------------------|
| `hard` | The address cannot receive mail: unknown user, disabled mailbox, or a domain with no mail server. | Yes |
| `block` | The receiving server refused the message because of the sending IP's or domain's reputation or policy, for example a blocklist listing or a mailbox provider's spam policy. The address itself is fine. | No. Block bounces also do not count toward your bounce rate, and you can send to the address again later. |

`bounce_reason` carries the receiving server's reply when there is one (for example `550 5.1.1 user unknown`).

An email the receiving server refuses for its size (for example `552 5.3.4 Message size exceeds fixed limit`) is not a bounce: it gets status `failed`, an `email.failed` webhook, `bounce_type: null` and the reply in `bounce_reason`. The recipient is not suppressed, so a smaller email (link to large files instead of attaching them) reaches them. See [attachment limits](#attachment-limits).

`opened_at` and `clicked_at` record the first open and the first tracked-link click. They stay `null` unless open or click tracking is on for the sending domain (see [Domains](https://docs.groundmail.dev/domains)).

### SDK

```ts
const { emails, next_cursor } = await client.emails.list({ limit: 10 })
```

### Error format

All errors return:

```json
{
  "error": {
    "message": "Human-readable message",
    "code": "validation_error",
    "details": {}
  }
}
```

| Status | When |
|--------|------|
| 400 | Invalid JSON, missing fields, invalid `from` (not exactly one address: a list, a group, a line break, or an unquoted name with special characters), invalid `to`, `cc` or `bcc` entry (not exactly one address: a list in one string, a group, a line break, or angle brackets in the name) |
| 401 | Missing/invalid Bearer token or API key |
| 403 | `from` domain not verified, sandbox/verified-domain sender used for recipients outside the account email, or send to other recipients without Free production unlocked (payment method on file). With tenants: `tenants_not_enabled` (your plan has no tenants), a paused or `transactional_only` tenant, or `from` on another tenant's domain (`domain_not_allowed`). `newsletter_not_enabled` for `category: "newsletter"` on an account not approved for newsletters |
| 404 | `tenant` names no tenant of this account |
| 409 | Idempotency key conflict |
| 422 | A recipient is suppressed or opted out of the category, Groundmail validation held back every recipient, or `sender` names a sender your team doesn't have |
| 413 | The request is over 20MB, Base64-encoded attachments included ([attachment limits](#attachment-limits)) |
| 429 | Send limit reached: the Free plan limit (`plan_limit`), or a new account's daily ramp-up limit (`daily_ramp_limit`, [details](https://docs.groundmail.dev/sending-limits#new-account-ramp-up)), or the tenant's own ramp or daily limit (`daily_ramp_limit` with `details.tenant`, [details](https://docs.groundmail.dev/tenants#sending-ramp)) |
| 502 | Mail server error on an email handed over during the request (one with attachments). A `queued` send gets `email.failed` instead |
| 503 | Mail delivery temporarily unavailable: nothing was sent, retry |

### Attachment limits

- Maximum 10 attachments per non-batch, non-scheduled send
- Maximum 10MB decoded size per attachment
- Maximum 20MB for the whole request (or SMTP message), Base64-encoded attachments included. Base64 makes files about a third larger, so that's about 14MB of files. A larger request gets `413` with code `validation_error`, and the [SMTP relay](https://docs.groundmail.dev/smtp) refuses a larger message with `552 5.3.4`. Link to large files instead of attaching them: many company mail servers refuse messages over 10MB anyway.
- Blocked filename extensions: `.exe`, `.bat`, `.cmd`, `.com`, `.scr`, `.js`, `.vbs`, `.dll`

---

## Examples

### curl

```bash
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"you@yourdomain.com","to":"user@example.com","subject":"Hello","html":"<p>Hi</p>"}'
```

### Node.js

```ts
import { Groundmail } from 'groundmail'

const client = new Groundmail(process.env.GROUNDMAIL_API_KEY!)
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hi</p>',
})
```

Throws `GroundmailError` on failure (`error.status`, `error.message`, `error.details`).

### CLI

```bash
groundmail emails send \
  --from you@yourdomain.com \
  --to user@example.com \
  --subject "Hello" \
  --html "<p>Hi</p>" \
  --tag order_id=ord_123 \
  --schedule 2026-08-01T12:00:00.000Z
```

Add `--watch` to wait until the recipient's mail server accepts or refuses it, with its reply and the time it took: see [Watch an email land](https://docs.groundmail.dev/cli#watch-an-email-land).

Signs in with `groundmail login`, or uses `GROUNDMAIL_API_KEY` or `--api-key`.

---

## OpenAPI

Machine-readable spec: [`openapi/groundmail.yaml`](https://docs.groundmail.dev/openapi.yaml)
