# SpacePost documentation (full text)

SpacePost is a Resend-compatible email API on AWS SES. Base URL https://api.spacepost.dev, auth `Authorization: Bearer sp_live_...`.
Index: https://docs.spacepost.dev/llms.txt

# Introduction

URL: https://docs.spacepost.dev/getting-started/introduction/

SpacePost is an email API for developers, built on Amazon SES. It speaks the **Resend API**: the same paths, the same JSON request and response shapes, the same error format and the same webhook signing scheme. If your code works with Resend, it works with SpacePost after changing a base URL.

You get the deliverability and price of SES, with the developer experience of a modern email API: a clean REST API, SDKs, a CLI, an MCP server, an SMTP relay for tools that cannot call an API, signed webhooks, scheduling, batch sending, audiences and broadcasts.

## What you can do

- **Send transactional email** with one `POST /emails` call: HTML, text, attachments, inline images, tags, custom headers, scheduling, idempotency keys.
- **Send up to 100 emails per request** with the batch endpoint.
- **Receive events** (`email.delivered`, `email.bounced`, `email.opened`...) on signed webhooks.
- **Send newsletters** to audiences with personalization and one-click unsubscribe.
- **Relay SMTP** from Supabase Auth, WordPress, Laravel, Django, Rails or any app that speaks SMTP.
- **Protect your reputation** with an automatic suppression list and automatic pausing when bounce or complaint rates get dangerous.

## How it works

```text
your app ──HTTPS──▶ api.spacepost.dev ──▶ queue ──▶ Amazon SES ──▶ recipient
   ▲                                                 │
   └──── signed webhooks ◀── events (SNS/SQS) ◀──────┘
```

1. Your request is validated and counted against your quota, then stored and queued. The API answers with an `id` immediately.
2. A worker builds the MIME message, drops suppressed recipients and hands it to SES with your domain's DKIM identity.
3. SES reports `delivered`, `bounced`, `complained`, `opened` and `clicked`. SpacePost records them on the email, updates `last_event`, adds hard bounces and complaints to your suppression list and calls your webhooks.

## How it compares

| | SpacePost | Resend | SendGrid | Raw AWS SES |
|---|---|---|---|---|
| API shape | Resend-compatible | Resend | Its own | AWS SDK / SMTP |
| Free tier | 3,000 / month | 3,000 / month, 100 / day | 100 / day | Sandbox |
| Entry paid plan | €9 for 50,000 | USD 20 for 50,000 | Varies | USD 0.10 per 1,000 |
| Overage per 1,000 | €0.25 | USD 0.90 | Varies | USD 0.10 |
| Dashboard, logs, webhooks | Yes | Yes | Yes | Build it yourself |
| Suppression list | Automatic | Automatic | Automatic | Build it yourself |
| SMTP relay | Yes | Yes | Yes | Yes |
| Audiences and broadcasts | Yes | Yes | Yes | No |
| Official Resend SDKs work | Yes (set the base URL) | Yes | No | No |

SpacePost prices are in EUR and exclude VAT. Resend's and AWS's prices are their published USD prices (Resend's as of 23 October 2026), shown as published and not converted.

> Note:
Free: 3,000 emails per month, 3 domains. Pro: €9, 50,000 emails, 10 domains. Scale: €35, 200,000 emails, 1,000 domains. Prices per month, excluding VAT. See [Plans and quotas](/account/plans-and-quotas/).

## Concepts

  
    Everything belongs to a team: domains, API keys, emails, webhooks, audiences. Quotas and reputation are tracked per team.
  
  
    You send from addresses on a verified domain, such as `hi@acme.com`. Verification takes three DKIM CNAMEs.
  
  
    Keys start with `sp_live_`. `full_access` keys use every endpoint, `sending_access` keys can only send, optionally from one domain.
  
  
    Each email has a UUIDv7 `id` and a `last_event` such as `delivered`. The full timeline is in the dashboard and on webhooks.
  

## Next steps

---

# Quickstart

URL: https://docs.spacepost.dev/getting-started/quickstart/

This guide takes you from nothing to a real email sent from your own domain.

1. **Create an API key**

   Open the [dashboard](https://app.spacepost.dev), go to **API keys** and click **Create API key**. Choose `full_access` while you experiment. Copy the key right away: it starts with `sp_live_` and is shown only once.

```bash
export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"
```

   > Note:
   Keep keys on the server. Never ship them in browser or mobile code. Create a `sending_access` key per service so you can revoke one without touching the others.
   

2. **Send a test email**

   You can send immediately, without a domain, using the shared test sender `onboarding@test.spacepost.dev`. It can only deliver to **your own team members' email addresses** and to the [test addresses](/sending/testing/) such as `delivered@test.spacepost.dev`.

   
     **Node.js**

```bash
npm install @spacepost/node
```
```ts title="send.ts"
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <onboarding@test.spacepost.dev>",
  to: ["delivered@test.spacepost.dev"],
  subject: "Hello from SpacePost",
  html: "<strong>It works!</strong>",
});

if (error) {
  console.error(error); // { statusCode, name, message }
} else {
  console.log("Sent", data.id);
}
```
     
     **cURL**

```bash
curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@test.spacepost.dev>",
    "to": ["delivered@test.spacepost.dev"],
    "subject": "Hello from SpacePost",
    "html": "<strong>It works!</strong>"
  }'
```
     
     **Python**

```python
import os
import requests

r = requests.post(
    "https://api.spacepost.dev/emails",
    headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
    json={
        "from": "Acme <onboarding@test.spacepost.dev>",
        "to": ["delivered@test.spacepost.dev"],
        "subject": "Hello from SpacePost",
        "html": "<strong>It works!</strong>",
    },
)
print(r.status_code, r.json())
```
     
     **Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := `{"from":"Acme <onboarding@test.spacepost.dev>","to":["delivered@test.spacepost.dev"],"subject":"Hello from SpacePost","html":"<strong>It works!</strong>"}`
	req, _ := http.NewRequest("POST", "https://api.spacepost.dev/emails", strings.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SPACEPOST_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}
```
     
   

   The response is `{ "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }`. Open the email in the dashboard to see its timeline: `sent`, then `delivered`.

3. **Add and verify your domain**

   To send to anyone, send from a domain you own.

```bash
curl -X POST https://api.spacepost.dev/domains \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme.com" }'
```

   The response lists the DNS `records` to create: three DKIM CNAMEs, plus an MX and a TXT record for the `send` subdomain (the custom return path). Add them at your DNS provider ([guides for Cloudflare, Route 53 and more](/domains/adding-and-verifying/#dns-provider-guides)), then ask SpacePost to check:

```bash
curl -X POST https://api.spacepost.dev/domains/$DOMAIN_ID/verify \
  -H "Authorization: Bearer $SPACEPOST_API_KEY"
```

   Or let the CLI do the work and watch DNS live:

```bash
npx spacepost domains doctor acme.com
```

   Verification usually completes within minutes. The domain `status` turns `verified` once DKIM is confirmed.

4. **Send from your domain**

```ts
await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: ["you@example.com"],
  subject: "First real email",
  html: "<p>Sent from my own domain.</p>",
});
```

> Note:
For the first 7 days a new account can send 100 emails per day. See [Account sandbox](/deliverability/sandbox/).

## What next

---

# Migrating from Resend

URL: https://docs.spacepost.dev/getting-started/migrating-from-resend/

SpacePost implements the Resend API: same paths, same field names, same response shapes and the same error format. Most apps migrate by changing a base URL and an API key.

1. **Create a SpacePost API key** in the [dashboard](https://app.spacepost.dev). SpacePost keys start with `sp_live_` (Resend keys start with `re_`).

2. **Add and verify your domain** in SpacePost. DNS records differ from Resend's, so add the new DKIM CNAMEs and the `send` MX/TXT records. You can keep Resend's records in place while you cut over, because DKIM selectors do not collide. See [Adding and verifying](/domains/adding-and-verifying/). Move your SPF/DMARC policy only if you changed the `send` subdomain.

3. **Switch the client.** Pick one of the options below.

   
     **Resend SDK, unchanged**

       Keep the official `resend` package. Set the base URL with an environment variable and use your SpacePost key:

```bash title=".env"
RESEND_API_KEY=sp_live_YOUR_API_KEY
RESEND_BASE_URL=https://api.spacepost.dev
```

```ts
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);
await resend.emails.send({ from: "Acme <hello@acme.com>", to: "you@example.com", subject: "Hi", html: "<p>Hi</p>" });
```

       Or pass it in code:

```ts
const resend = new Resend("sp_live_YOUR_API_KEY", { baseUrl: "https://api.spacepost.dev" });
```
     
     **@spacepost/node**

       Swap the import. The method names and `{ data, error }` return shape are the same.

```diff
- import { Resend } from "resend";
- const resend = new Resend(process.env.RESEND_API_KEY);
+ import { SpacePost } from "@spacepost/node";
+ const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

- await resend.emails.send({ ... });
+ await spacepost.emails.send({ ... });
```
     
     **Raw HTTP / other languages**

       Change the host and the key. Paths and bodies are identical.

```diff
- curl https://api.resend.com/emails -H "Authorization: Bearer re_..."
+ curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_..."
```
     
     **SMTP**

       Change host, port and password, and use STARTTLS. The username `resend` is accepted as an alias for `spacepost`.

       ```text
Host: smtp.spacepost.dev    Port: 25976 (STARTTLS)
User: spacepost             Password: sp_live_YOUR_API_KEY
```
     
   

4. **Recreate your webhooks.** Create each endpoint again in SpacePost (`POST /webhooks`) and store the new `signing_secret`. Verification code written for Resend or Svix keeps working because SpacePost sends the same Standard Webhooks headers (plus `svix-*` duplicates). See [Verifying signatures](/webhooks/verifying/).

5. **Move audiences and contacts.** Create audiences and import contacts through `POST /audiences/{id}/contacts`. Placeholders such as `{{{FIRST_NAME|fallback}}}` and `{{{RESEND_UNSUBSCRIBE_URL}}}` work unchanged in broadcasts.

6. **Send a test, then cut over.** Send to `delivered@test.spacepost.dev`, check the webhook arrives, then deploy.

## Parity table

| Resend feature | SpacePost | Notes |
|---|---|---|
| `POST /emails` | Supported | `to`/`cc`/`bcc`/`reply_to` up to 50 each; camelCase aliases `replyTo`, `scheduledAt` accepted |
| `POST /emails/batch` | Supported | Up to 100 emails; attachments and `scheduled_at` are allowed per email; all-or-nothing |
| `GET /emails/{id}`, `GET /emails` | Supported | List omits bodies |
| `PATCH /emails/{id}` | Supported | Reschedule scheduled emails |
| `POST /emails/{id}/cancel` | Supported | Scheduled emails only |
| Attachments (`content`, `path`) | Supported | `path` must be https |
| Tags, custom headers | Supported | Same constraints on tag characters |
| `Idempotency-Key` | Supported | 24 hours, `POST /emails` and `/emails/batch` |
| Domains (create, get, list, verify, update, delete) | Supported | `open_tracking`, `click_tracking` |
| API keys | Supported | `full_access`, `sending_access`, optional `domain_id` |
| Webhooks, Standard Webhooks signing | Supported | Also `svix-*` headers |
| Audiences, contacts, broadcasts | Supported | Contacts live under `/audiences/{id}/contacts` |
| Suppressions API | Supported | Extra: list, add and remove entries |
| Tenants (platform mode) | SpacePost only | Isolated reputation per customer; see [Platform mode](/platform/tenants/). The Resend SDK drops `tenant_id`; use `resend.post` or tenant-owned domains |
| SMTP relay | Supported | `smtp.spacepost.dev:25976` with STARTTLS (no implicit TLS on 465 yet) |
| Inbound email | Not yet | |
| Templates editor | Not yet | Use React Email or your own HTML |

## Differences to know about

> Note:
SpacePost keys start with `sp_live_`. A `re_...` key is rejected with `403 invalid_api_key`. If you see that error after migrating, an old `RESEND_API_KEY` is still deployed somewhere.

- **`last_event` values.** Resend's values (`queued`, `scheduled`, `sent`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `opened`, `clicked`, `canceled`, `failed`) are all present. SpacePost adds `suppressed`, used when every recipient was on your suppression list. Status never moves backwards: an `opened` event arriving before `delivered` keeps the later state.
- **Extra webhook event.** `email.suppressed` fires when a recipient is skipped because it is suppressed. Subscribe only to the events you handle. Payloads are otherwise identical to Resend's; `data.tenant_id` is added for tenant mail.
- **Rate limit.** 10 requests per second per team (25 on Scale) versus 2 on Resend, with the same `ratelimit-*` headers.
- **Pricing.** Pro is €9 for 50,000 emails with €0.25 per extra 1,000, billed in EUR excluding VAT (Resend Pro: USD 20 with USD 0.90 per extra 1,000, Resend's USD prices as of 23 October 2026). After the first 7 days every plan, including Free, has a daily cap that grows with your sending: the larger of 1,000 and twice your best day in the last 14 days, up to 50,000 per day. See [Plans and quotas](/account/plans-and-quotas/).
- **What counts as an email.** Every recipient counts: one email to 3 recipients (to, cc and bcc together) counts 3 against your quota.
- **Test sender.** `onboarding@test.spacepost.dev` replaces `onboarding@resend.dev`. Test inboxes live at `test.spacepost.dev` instead of `resend.dev`: `delivered@`, `bounced@`, `complained@`, `delayed@`, plus `softbounced@` (SpacePost only).
- **New-account sandbox.** The first 7 days are limited to 100 emails per day. See [Verification and limits](/account/verification-and-limits/).
- **Automatic pausing.** Teams with abnormal bounce or complaint rates are paused automatically. See [Automatic pausing](/deliverability/auto-pausing/).
- **Base URL.** `https://api.spacepost.dev`, with paths at the root. A `/v1` prefix is also accepted (`https://api.spacepost.dev/v1/emails`).

---

# Send an email

URL: https://docs.spacepost.dev/sending/send-email/

`https://api.spacepost.dev/emails`

Send one email to up to 50 `to` recipients, with optional `cc`, `bcc`, attachments, tags, headers and a schedule. The call returns as soon as the email is accepted and queued; delivery happens asynchronously and is reported by [webhooks](/webhooks/overview/).

## Example

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: ["user@example.com"],
  cc: ["manager@example.com"],
  bcc: ["archive@acme.com"],
  replyTo: "support@acme.com",
  subject: "Your invoice",
  html: "<p>Invoice attached.</p>",
  text: "Invoice attached.",
  headers: { "X-Entity-Ref-ID": "inv_1042" },
  tags: [{ name: "category", value: "invoice" }],
});

if (error) {
  console.error(error.statusCode, error.name, error.message);
} else {
  console.log("Email id:", data.id);
}
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "from": "Acme <hello@acme.com>",
        "to": ["user@example.com"],
        "cc": ["manager@example.com"],
        "bcc": ["archive@acme.com"],
        "reply_to": "support@acme.com",
        "subject": "Your invoice",
        "html": "<p>Invoice attached.</p>",
        "text": "Invoice attached.",
        "headers": { "X-Entity-Ref-ID": "inv_1042" },
        "tags": [{ "name": "category", "value": "invoice" }]
      }'
  ```

**Python**

  ```python
    import os, requests

    r = requests.post(
        "https://api.spacepost.dev/emails",
        headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
        json={
            "from": "Acme <hello@acme.com>",
            "to": ["user@example.com"],
            "cc": ["manager@example.com"],
            "bcc": ["archive@acme.com"],
            "reply_to": "support@acme.com",
            "subject": "Your invoice",
            "html": "<p>Invoice attached.</p>",
            "text": "Invoice attached.",
            "headers": {"X-Entity-Ref-ID": "inv_1042"},
            "tags": [{"name": "category", "value": "invoice"}],
        },
    )
    print(r.json())
  ```

**Go**

  ```go
    payload := map[string]any{
    	"from":     "Acme <hello@acme.com>",
    	"to":       []string{"user@example.com"},
    	"cc":       []string{"manager@example.com"},
    	"reply_to": "support@acme.com",
    	"subject":  "Your invoice",
    	"html":     "<p>Invoice attached.</p>",
    	"tags":     []map[string]string{{"name": "category", "value": "invoice"}},
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.spacepost.dev/emails", bytes.NewReader(b))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SPACEPOST_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    res, err := http.DefaultClient.Do(req)
  ```

**PHP**

  ```php
    $ch = curl_init('https://api.spacepost.dev/emails');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SPACEPOST_API_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'from' => 'Acme <hello@acme.com>',
            'to' => ['user@example.com'],
            'reply_to' => 'support@acme.com',
            'subject' => 'Your invoice',
            'html' => '<p>Invoice attached.</p>',
            'tags' => [['name' => 'category', 'value' => 'invoice']],
        ]),
    ]);
    echo curl_exec($ch);
  ```

**Ruby**

  ```ruby
    require "net/http"
    require "json"

    uri = URI("https://api.spacepost.dev/emails")
    req = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV["SPACEPOST_API_KEY"]}", "Content-Type" => "application/json")
    req.body = {
      from: "Acme <hello@acme.com>", to: ["user@example.com"], reply_to: "support@acme.com",
      subject: "Your invoice", html: "<p>Invoice attached.</p>",
      tags: [{ name: "category", value: "invoice" }]
    }.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```
  

```json title="Response (200)"
{ "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }
```

## Request body

- `from` (string, required): Sender, as `email@domain.com` or `Name <email@domain.com>`. The domain (or a parent domain) must be verified. The only exception is `onboarding@test.spacepost.dev`, see Testing.
- `to` (string | string[], required): Recipients. Up to 50 addresses.
- `subject` (string, required): 1 to 998 characters.
- `html` (string): HTML body. At least one of `html` or `text` is required.
- `text` (string): Plain-text body. If you only send `html`, a text alternative is generated for you, which improves deliverability.
- `cc` (string | string[]): Up to 50 addresses.
- `bcc` (string | string[]): Up to 50 addresses. Never written into message headers.
- `reply_to` (string | string[]): Up to 50 addresses. The camelCase alias `replyTo` is also accepted.
- `scheduled_at` (string): ISO 8601 date or natural language such as `in 1 hour`, at most 30 days ahead. Alias `scheduledAt`.
- `headers` (object): Custom headers as string keys and string values.
- `attachments` (object[]): Up to 50 attachments, each with `filename` and exactly one of `content` or `path`.
- `tags` (object[]): Up to 50 `{ name, value }` pairs. Names and values: 1 to 256 characters of `A-Z a-z 0-9 _ -`.
- `tenant_id` (string): Platform mode: send on behalf of a tenant (our id or your `external_id`). Optional when the `from` domain belongs to a tenant. Alias `tenantId` in the Node SDK. See Platform mode.

More: [domain verification](/domains/adding-and-verifying/), [Testing](/sending/testing/), [Scheduling](/sending/scheduling/), [Custom headers](/sending/headers/), [Attachments](/sending/attachments/), [Tags](/sending/tags/), [Platform mode](/platform/tenants/).

Addresses in every field may use the `Name <email@domain.com>` form.

### Limits at a glance

| Limit | Value |
|---|---|
| Recipients per field (`to`, `cc`, `bcc`, `reply_to`) | 50 |
| Subject length | 998 characters |
| Attachments | 50 per email, `filename` up to 255 characters |
| Tags | 50 per email, name and value 1 to 256 characters of `A-Z a-z 0-9 _ -` |
| Total message size | 40 MB including attachments and encoding overhead |
| Scheduling horizon | 30 days |
| Emails per batch request | 100 ([Batch sending](/sending/batch/)) |

> Note:
Quota is counted per recipient: an email with 1 `to`, 1 `cc` and 2 `bcc` addresses counts as 4 emails. See [Plans and quotas](/account/plans-and-quotas/).

## Response

Success returns `200` with the new email `id` (a UUIDv7). Use it with [`GET /emails/{id}`](/api-reference/) to read the email and its `last_event`.

## What can go wrong

| Status | `name` | Meaning |
|---|---|---|
| 401 | `missing_api_key` | No `Authorization: Bearer` header. |
| 403 | `invalid_api_key` | Key is unknown, revoked or not a SpacePost key (`sp_live_...`). |
| 401 | `restricted_api_key` | A domain-restricted key was used with a different `from` domain. |
| 403 | `invalid_from_address` | The `from` domain is not verified for your team. |
| 403 | `validation_error` | Using `test.spacepost.dev` as sender with a recipient that is not a team member or a test address. |
| 403 | `sending_paused` | Your team is [paused](/deliverability/auto-pausing/). |
| 422 | `validation_error` | A field is missing or invalid. `message` names the field, for example `` `to`: Invalid email address ``. |
| 429 | `daily_quota_exceeded` | Daily limit reached: the new-account [sandbox](/deliverability/sandbox/), your [trust-level cap](/account/verification-and-limits/) or a tenant's `daily_limit`. |
| 429 | `monthly_quota_exceeded` | Free plan monthly limit reached. |
| 429 | `rate_limit_exceeded` | More than your requests-per-second limit. See [Rate limits](/api/rate-limits/). |

See the complete list in [Errors](/api/errors/).

## After the call

The email moves through statuses, exposed as `last_event`: `queued` (or `scheduled`), `sent`, then `delivered`, `delivery_delayed`, `bounced`, `complained`, `opened` or `clicked`. If every recipient is on your [suppression list](/deliverability/bounces-and-complaints/), nothing is sent and the status becomes `suppressed`.

---

# Batch sending

URL: https://docs.spacepost.dev/sending/batch/

`https://api.spacepost.dev/emails/batch`

The body is a JSON **array** of up to 100 objects, each with the same fields as [Send an email](/sending/send-email/). Batching saves round trips and counts as a single request against your [rate limit](/api/rate-limits/).

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.batch.send(
  [
    { from: "Acme <hello@acme.com>", to: ["a@example.com"], subject: "Hi Ada", html: "<p>Hi Ada</p>" },
    { from: "Acme <hello@acme.com>", to: ["b@example.com"], subject: "Hi Bob", html: "<p>Hi Bob</p>" },
  ],
  { idempotencyKey: "weekly-digest-2026-w43" },
);

if (error) console.error(error);
else console.log(data.data.map((e) => e.id)); // ids in input order
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails/batch \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: weekly-digest-2026-w43" \
      -d '[
        { "from": "Acme <hello@acme.com>", "to": ["a@example.com"], "subject": "Hi Ada", "html": "<p>Hi Ada</p>" },
        { "from": "Acme <hello@acme.com>", "to": ["b@example.com"], "subject": "Hi Bob", "html": "<p>Hi Bob</p>" }
      ]'
  ```

**Python**

  ```python
    r = requests.post(
        "https://api.spacepost.dev/emails/batch",
        headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
        json=[
            {"from": "Acme <hello@acme.com>", "to": ["a@example.com"], "subject": "Hi Ada", "html": "<p>Hi Ada</p>"},
            {"from": "Acme <hello@acme.com>", "to": ["b@example.com"], "subject": "Hi Bob", "html": "<p>Hi Bob</p>"},
        ],
    )
    print(r.json())  # {"data": [{"id": "..."}, {"id": "..."}]}
    ```
  

```json title="Response (200)"
{
  "data": [
    { "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" },
    { "id": "0192e1c4-7a3c-7a02-8e10-6c0f9d7a2b31" }
  ]
}
```

Ids are returned in the same order as the input array.

## Behavior

- **All or nothing.** If any email in the array is invalid, the whole request fails with a `validation_error` and nothing is stored. The `message` says which email (`(email 1)`).
- **Quota is checked once** for the total recipient count. If it would exceed your limit, the whole batch is rejected.
- **Everything is allowed per email**: attachments, tags, custom headers, `scheduled_at` and [`tenant_id`](/platform/tenants/). A paused tenant or an over-cap tenant fails the whole batch.
- **Idempotency keys** apply to the whole batch. Retry safely with the same key.
- The batch size limit is **100 emails**; larger arrays return `422`. Chunk bigger lists.

> Note:
Use [broadcasts](/audiences/broadcasts/) to an audience. They handle personalization, unsubscribe links and suppression for you.

## Chunking helper

```ts
import { SpacePost, type SendEmailOptions } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

export async function sendAll(emails: SendEmailOptions[], jobId: string) {
  for (let i = 0; i < emails.length; i += 100) {
    const chunk = emails.slice(i, i + 100);
    const { error } = await spacepost.batch.send(chunk, { idempotencyKey: `${jobId}-chunk-${i / 100}` });
    if (error) throw new Error(`${error.name}: ${error.message}`);
  }
}
```

---

# Scheduling

URL: https://docs.spacepost.dev/sending/scheduling/

Add `scheduled_at` to any send request to deliver later. The email is accepted immediately, gets the status `scheduled` and an `email.scheduled` webhook fires.

## Formats

| Format | Example |
|---|---|
| ISO 8601 | `2026-11-01T09:00:00Z`, `2026-11-01T09:00:00+01:00` |
| Natural language | `in 30 seconds`, `in 10 minutes`, `in 2 hours`, `in 1 day`, `in 1 week` |

Natural language is `in <number> <unit>` where unit is one of `second`, `sec`, `minute`, `min`, `hour`, `hr`, `day`, `week` (plural `s` optional). The text is case-insensitive.

Other rules:

- **Maximum 30 days** in the future. Beyond that the API returns `422 validation_error`.
- A time in the past, or less than about a second ahead, is treated as **send now**.
- ISO strings without a timezone offset are interpreted by the server's date parser; always include `Z` or an offset.
- Both `scheduled_at` and `scheduledAt` are accepted.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Your trial ends tomorrow",
  html: "<p>Reminder.</p>",
  scheduledAt: "in 1 day", // or an ISO date: "2026-11-01T09:00:00Z"
});

if (error) console.error(error);
else console.log("Scheduled", data.id);
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{
        "from": "Acme <hello@acme.com>",
        "to": ["user@example.com"],
        "subject": "Your trial ends tomorrow",
        "html": "<p>Reminder.</p>",
        "scheduled_at": "2026-11-01T09:00:00Z"
      }'
  ```

**Python**

  ```python
    requests.post(
        "https://api.spacepost.dev/emails",
        headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
        json={
            "from": "Acme <hello@acme.com>",
            "to": ["user@example.com"],
            "subject": "Your trial ends tomorrow",
            "html": "<p>Reminder.</p>",
            "scheduled_at": "in 1 day",
        },
    )
    ```
  

## Reschedule

Only emails with status `scheduled` can be changed. `PATCH /emails/{id}` replaces the time; a new job is queued and the old one becomes a no-op.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.emails.update({
  id: "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
  scheduledAt: "in 2 hours",
});
if (error) console.error(error);
```
  
  **cURL**

    ```bash
    curl -X PATCH https://api.spacepost.dev/emails/$EMAIL_ID \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{ "scheduled_at": "2026-11-02T09:00:00Z" }'
    ```
  

```json title="Response (200)"
{ "object": "email", "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }
```

## Cancel

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.emails.cancel("0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10");
if (error) console.error(error); // 422 validation_error if it is no longer scheduled
```
  
  **cURL**

```bash
curl -X POST https://api.spacepost.dev/emails/$EMAIL_ID/cancel -H "Authorization: Bearer $SPACEPOST_API_KEY"
```
  

The status becomes `canceled` and the email is never sent. Cancelling or rescheduling an email that is no longer `scheduled` returns `422 validation_error` ("Only scheduled emails can be canceled").

> Note:
Recipients are counted against your quota when the email is accepted, not when it is sent. Cancelling does not currently refund quota.

## Over SMTP

Set the `X-SpacePost-Scheduled-At` header to an ISO date or natural-language value. See [SMTP relay](/tools/smtp/).

---

# Attachments

URL: https://docs.spacepost.dev/sending/attachments/

`attachments` is an array of up to **50** objects. Each attachment needs a `filename` and **exactly one** of `content` or `path`.

- `filename` (string, required): 1 to 255 characters. Shown to the recipient.
- `content` (string): File bytes as base64. The SDK also accepts a `Buffer`/`Uint8Array` and encodes it for you. Use this or `path`.
- `path` (string): A public https URL. SpacePost downloads it when the email is sent. Use this or `content`.
- `content_type` (string): MIME type, such as `application/pdf`. Alias `contentType` in the SDK.
- `content_id` (string): Makes the attachment inline, referenceable as `cid:<content_id>` in your HTML. Alias `contentId` in the SDK.

## Limits

- The whole message, including all attachments after base64 encoding, must be under **40 MB**. Base64 inflates files by about 33%, so keep the raw total under roughly 30 MB.
- URL attachments (`path`) must use `https`, must resolve to a public address (private networks are refused), are fetched with a 10 second timeout and must not redirect. Fetch failures mark the email `failed`.
- Attachment bytes are removed from storage once the email is sent; only metadata (name, type, size) is kept in the log.
- Attachments don't cost extra on any standard plan. SpacePost is built for transactional and marketing email, not bulk file delivery: if your attachment volume is unusually high compared with your email volume, we may contact you about a custom plan (see the [Acceptable Use Policy](https://spacepost.dev/legal/acceptable-use)).

## Attach a file by content

  **Node.js**

    ```ts
import { readFile } from "node:fs/promises";
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <billing@acme.com>",
  to: "user@example.com",
  subject: "Invoice 1042",
  text: "Your invoice is attached.",
  attachments: [{ filename: "invoice-1042.pdf", content: await readFile("invoice-1042.pdf"), contentType: "application/pdf" }],
});

console.log(error ?? data);
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d "{
        \"from\": \"Acme <billing@acme.com>\",
        \"to\": [\"user@example.com\"],
        \"subject\": \"Invoice 1042\",
        \"text\": \"Your invoice is attached.\",
        \"attachments\": [{
          \"filename\": \"invoice-1042.pdf\",
          \"content_type\": \"application/pdf\",
          \"content\": \"$(base64 -w0 invoice-1042.pdf)\"
        }]
      }"
  ```
  On macOS use `base64 -i invoice-1042.pdf` (no `-w0`).

**Python**

  ```python
    import base64

    with open("invoice-1042.pdf", "rb") as f:
        content = base64.b64encode(f.read()).decode()

    requests.post(
        "https://api.spacepost.dev/emails",
        headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
        json={
            "from": "Acme <billing@acme.com>",
            "to": ["user@example.com"],
            "subject": "Invoice 1042",
            "text": "Your invoice is attached.",
            "attachments": [{"filename": "invoice-1042.pdf", "content_type": "application/pdf", "content": content}],
        },
    )
    ```
  

## Attach a file by URL

```json
{
  "from": "Acme <billing@acme.com>",
  "to": ["user@example.com"],
  "subject": "Your report",
  "text": "Report attached.",
  "attachments": [{ "filename": "report.pdf", "path": "https://files.acme.com/reports/2026-10.pdf" }]
}
```

> Note:
Giving both `content` and `path`, or neither, returns `422`: "Each attachment needs exactly one of `content` or `path`".

## Inline images

Set a `content_id` and reference it with a `cid:` URL in your HTML.

```ts
import { readFile } from "node:fs/promises";
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: '<img src="cid:logo" alt="Acme" width="120" /><p>Welcome aboard.</p>',
  attachments: [{ filename: "logo.png", content: await readFile("logo.png"), contentType: "image/png", contentId: "logo" }],
});
```

Inline images are sent as part of the message and display without a network request, but many clients (Gmail on the web in particular) show them best when they are small. For large images host them on your own CDN and use a normal `https://` URL.

---

# Tags

URL: https://docs.spacepost.dev/sending/tags/

Tags are `{ name, value }` pairs attached to an email. They are stored with the email, returned by `GET /emails/{id}` and echoed in every [webhook payload](/webhooks/event-types/) for that email (as an object, `"tags": { "category": "welcome" }`). Use them to tie events back to your own records without storing the SpacePost `id`.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: "<p>Hi</p>",
  tags: [
    { name: "category", value: "welcome" },
    { name: "user_id", value: "u_1042" },
  ],
});
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{
        "from": "Acme <hello@acme.com>",
        "to": ["user@example.com"],
        "subject": "Welcome",
        "html": "<p>Hi</p>",
        "tags": [{ "name": "category", "value": "welcome" }, { "name": "user_id", "value": "u_1042" }]
      }'
  ```

**SMTP**

  ```text
    X-SpacePost-Tags: category=welcome, user_id=u_1042
    ```
  

## Rules

- Up to **50** tags per email.
- `name` and `value` are each **1 to 256 characters** and may contain only ASCII letters, numbers, underscores and dashes (`A-Z a-z 0-9 _ -`).
- Spaces, dots, `@` and non-ASCII characters are rejected with a `422`. Hash or slug values such as email addresses first, for example `user_1042` or a SHA-256 hex digest.

> Note:
Good tag names: `category`, `campaign`, `user_id`, `order_id`, `environment`. Do not put personal data in tags.

---

# Custom headers

URL: https://docs.spacepost.dev/sending/headers/

`headers` is an object of string keys to string values, written into the message as-is.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Weekly digest",
  html: "<p>...</p>",
  headers: {
    "List-Unsubscribe": "<https://acme.com/unsubscribe?u=1042>, <mailto:unsubscribe@acme.com>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
    "X-Entity-Ref-ID": "digest-2026-w43-1042",
  },
});
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{
        "from": "Acme <hello@acme.com>",
        "to": ["user@example.com"],
        "subject": "Weekly digest",
        "html": "<p>...</p>",
        "headers": {
          "List-Unsubscribe": "<https://acme.com/unsubscribe?u=1042>",
          "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
        }
      }'
    ```
  

## Common uses

| Header | Purpose |
|---|---|
| `List-Unsubscribe` and `List-Unsubscribe-Post` | One-click unsubscribe (RFC 8058). Required by Gmail and Yahoo for bulk senders. Broadcasts add it automatically. |
| `X-Entity-Ref-ID` | A unique value per email. Stops Gmail from collapsing similar messages into one thread or hiding the footer. |
| `In-Reply-To`, `References` | Thread a message under an existing conversation. |
| `X-*` | Any application-specific metadata. Over SMTP, `X-*` headers are forwarded, except SpacePost's own `X-SpacePost-*` control headers. |

> Note:
Do not set `From`, `To`, `Subject`, `Date`, `Message-ID` or `DKIM-Signature` through `headers`. Use the dedicated fields; SES manages the rest.

---

# Idempotency keys

URL: https://docs.spacepost.dev/sending/idempotency/

Networks fail. If a request times out you cannot tell whether the email was accepted. Send an `Idempotency-Key` header and retry freely: the same key with the same body returns the **original response** and sends the email **once**.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send(
  { from: "Acme <hello@acme.com>", to: "user@example.com", subject: "Receipt", html: "<p>Thanks</p>" },
  { idempotencyKey: "receipt-order-1042" },
);

console.log(error ?? data);
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" \
      -H "Idempotency-Key: receipt-order-1042" \
      -H "Content-Type: application/json" \
      -d '{ "from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>" }'
  ```

**Python**

  ```python
    requests.post(
        "https://api.spacepost.dev/emails",
        headers={
            "Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}",
            "Idempotency-Key": "receipt-order-1042",
        },
        json={"from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>"},
    )
    ```
  

## Rules

- Supported on `POST /emails` and `POST /emails/batch`.
- The key is **1 to 256 characters**.
- Keys are scoped to your team and remembered for **24 hours**.
- Same key and same request body: the stored response is returned (same status, same body), nothing new is sent.
- Same key and a **different** body: `409 invalid_idempotent_request`.
- Same key while the first request is still running: `409 concurrent_idempotent_requests`. Wait a moment and retry.
- A key outside 1 to 256 characters: `400 invalid_idempotency_key`.
- Requests that fail are not stored, so you can fix the problem and reuse the key.

"Same body" means the parsed JSON is identical. Changing any field, including `scheduled_at: "in 1 hour"` (which is evaluated at request time), counts as a different request.

## Choosing keys

Derive the key from the business event, not from a random value generated at retry time:

| Good | Bad |
|---|---|
| `receipt-order-1042` | `crypto.randomUUID()` on each attempt |
| `welcome-user-u_1042` | `Date.now()` |
| `digest-2026-w43-chunk-3` | The same constant for every email |

> Note:
A random UUID is fine if you generate it **once** per logical send (for example when you enqueue a job) and reuse it on every retry of that job.

---

# Testing

URL: https://docs.spacepost.dev/sending/testing/

Never test with made-up addresses at real domains: they bounce and hurt your sender reputation. SpacePost provides test inboxes at `test.spacepost.dev`. Mail to them is never delivered anywhere, but the full event pipeline runs, including webhooks.

| Address | Simulates | Events you will see |
|---|---|---|
| `delivered@test.spacepost.dev` | Successful delivery | `email.sent`, `email.delivered` |
| `bounced@test.spacepost.dev` | Hard bounce (permanent) | `email.sent`, `email.bounced` |
| `complained@test.spacepost.dev` | Recipient marks as spam | `email.sent`, `email.delivered`, `email.complained` |
| `delayed@test.spacepost.dev` | Temporary delivery problem | `email.sent`, `email.delivery_delayed` |
| `softbounced@test.spacepost.dev` | Soft bounce (mailbox full); the third within 30 days suppresses the address | `email.sent`, `email.delivery_delayed` |

## Labels

Add `+label` to run multiple scenarios in parallel and tell them apart: `delivered+signup@test.spacepost.dev`, `bounced+case-17@test.spacepost.dev`. The label is ignored when choosing the outcome.

> Note:
Simulated hard bounces and complaints behave like real ones: the address is added to your [suppression list](/deliverability/bounces-and-complaints/) and counts toward [automatic pausing](/deliverability/auto-pausing/) thresholds. Delete test entries from **Suppressions** in the dashboard, or with `DELETE /suppressions/{email}`, after running a bounce test.

## The test sender

Before you verify a domain you can send from **`onboarding@test.spacepost.dev`**. It is restricted:

- it can send **only to your own team members' email addresses** and to `@test.spacepost.dev` addresses;
- any other recipient is rejected with `403 validation_error`;
- once your domain is verified, send from your own address.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <onboarding@test.spacepost.dev>",
  to: ["delivered@test.spacepost.dev", "bounced+case-1@test.spacepost.dev"],
  subject: "Test",
  html: "<p>Test</p>",
});
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{
        "from": "Acme <onboarding@test.spacepost.dev>",
        "to": ["delivered@test.spacepost.dev"],
        "subject": "Test",
        "html": "<p>Test</p>"
      }'
    ```
  

## Testing your webhook handler

1. Create a webhook that points at a tunnel to your machine (for example `https://abc123.ngrok.app/webhooks/spacepost`), subscribed to the events you handle.
2. Send to `delivered@`, `bounced@`, `complained@` and `delayed@`.
3. Check that your handler verifies the signature and responds `2xx`.

Test sends count toward your monthly quota like any other email.

---

# Adding and verifying a domain

URL: https://docs.spacepost.dev/domains/adding-and-verifying/

To send from `hello@acme.com` you prove you own `acme.com` by publishing DNS records. Verification sets up DKIM signing (so receivers know the mail is really yours) and a custom return path (so SPF and DMARC align with your domain).

> Note:
New teams complete a short **sending profile** first and some domains are refused (free mail providers, domains registered in the last 7 days). See [Account verification and sending limits](/account/verification-and-limits/).

1. **Add the domain**

   
     **Node.js**

       ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: domain, error } = await spacepost.domains.create({ name: "acme.com" });
if (error) throw new Error(`${error.name}: ${error.message}`);

console.log(domain.id, domain.status); // "not_started" or "pending"
for (const r of domain.records ?? []) {
  console.log(`${r.type.padEnd(5)} ${r.name} -> ${r.value}${r.priority ? ` (priority ${r.priority})` : ""}`);
}
```
     
     **cURL**

       ```bash
       curl -X POST https://api.spacepost.dev/domains \
         -H "Authorization: Bearer $SPACEPOST_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{ "name": "acme.com" }'
  ```

**Python**

  ```python
       r = requests.post(
           "https://api.spacepost.dev/domains",
           headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
           json={"name": "acme.com"},
       )
       for rec in r.json()["records"]:
           print(rec["type"], rec["name"], rec["value"])
       ```
     
   

   You can also use the dashboard or `spacepost domains add acme.com`.

2. **Create the DNS records**

   The response contains a `records` array and a `recommended_records` array (DMARC):

   ```json title="Response (abridged)"
   {
     "object": "domain",
     "id": "0192e1c4-0000-7000-8000-000000000001",
     "name": "acme.com",
     "status": "not_started",
     "region": "eu-central-1",
     "open_tracking": false,
     "click_tracking": false,
     "records": [
       { "record": "DKIM", "name": "a1b2c3d4e5f6._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "a1b2c3d4e5f6.dkim.amazonses.com" },
       { "record": "DKIM", "name": "g7h8i9j0k1l2._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "g7h8i9j0k1l2.dkim.amazonses.com" },
       { "record": "DKIM", "name": "m3n4o5p6q7r8._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "m3n4o5p6q7r8.dkim.amazonses.com" },
       { "record": "SPF", "name": "send", "type": "MX", "ttl": "Auto", "status": "not_started", "value": "feedback-smtp.eu-central-1.amazonses.com", "priority": 10 },
       { "record": "SPF", "name": "send", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "\"v=spf1 include:amazonses.com ~all\"" }
     ],
     "recommended_records": [
       { "record": "DMARC", "name": "_dmarc", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "\"v=DMARC1; p=none;\"" }
     ]
   }
   ```

   Add them at your DNS provider. See [the records explained](#the-records-explained) below and the [provider guides](#dns-provider-guides).

3. **Verify**

   DNS changes can take a few minutes (rarely hours). SpacePost rechecks pending domains automatically, and you can trigger a check at any time:

   
     **Node.js**

       ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
const id = "0192e1c4-0000-7000-8000-000000000001";

const { error } = await spacepost.domains.verify(id); // asks SpacePost to re-check DNS now
if (error) throw new Error(error.message);

const { data: domain } = await spacepost.domains.get(id);
console.log(domain?.status); // "verified" once DKIM is confirmed
```
     
     **cURL**

```bash
curl -X POST https://api.spacepost.dev/domains/$DOMAIN_ID/verify -H "Authorization: Bearer $SPACEPOST_API_KEY"
curl https://api.spacepost.dev/domains/$DOMAIN_ID -H "Authorization: Bearer $SPACEPOST_API_KEY"
```
     
     **CLI**

```bash
spacepost domains verify acme.com
spacepost domains doctor acme.com   # looks up each record live and tells you what is missing or wrong
```
     
   

## The records explained

Record names in the API are **relative** to your domain (`send`, `_dmarc`, `a1b2c3d4e5f6._domainkey`). Some DNS providers want the full name (`send.acme.com`); the [provider guides](#dns-provider-guides) say which.

| Record | Type | Name | Value | Purpose |
|---|---|---|---|---|
| DKIM (x3) | CNAME | `<token>._domainkey` | `<token>.dkim.amazonses.com` | Publishes the public keys Amazon SES rotates for you ("Easy DKIM"). Receivers use them to verify that each message was signed by your domain and not altered. **Required**: verification depends on all three. |
| Return path | MX | `send` | `feedback-smtp.<region>.amazonses.com`, priority `10` | Receives bounce and complaint notifications addressed to `send.acme.com`. Together with the TXT below it forms a custom MAIL FROM domain. |
| Return path | TXT | `send` | `v=spf1 include:amazonses.com ~all` | SPF for the return-path subdomain. Because the envelope sender is on your domain, SPF aligns with your `From` address, which DMARC needs. |
| DMARC (recommended) | TXT | `_dmarc` | `v=DMARC1; p=none;` | Tells receivers what to do with mail that fails authentication, and is required by Gmail and Yahoo for bulk senders. See [DMARC](/domains/dmarc/). |

> Note:
The API shows TXT values wrapped in quotes (`"v=spf1 ..."`). Most DNS dashboards add the quotes themselves; enter the value **without** them.

> Note:
The `send` subdomain can be renamed with `custom_return_path` when you add the domain. See [Custom return path](/domains/return-path/).

Building a platform that sends for your own customers? Pass `tenant_id` (a tenant id or your `external_id`) to make the domain tenant-owned; mail from it is then attributed to that tenant automatically. See [Platform mode](/platform/tenants/).

## Statuses

| Status | Meaning |
|---|---|
| `not_started` | Domain added, DNS not yet seen. |
| `pending` | SpacePost is checking DNS. |
| `verified` | DKIM is confirmed. You can send from this domain. |
| `temporary_failure` | A lookup failed temporarily. It is retried automatically. |
| `failed` | DNS was not found within 72 hours, or a record is wrong. Fix the records and call verify again. |

The domain is `verified` as soon as DKIM passes. If only the return-path records are missing, mail still sends but SPF alignment falls back to Amazon's domain, which weakens DMARC alignment. Fix it for best deliverability.

Each record in `records` has its own `status` with the same values, so you can see exactly which one is missing.

## Sending from subdomains

If `acme.com` is verified you can send from any subdomain (`news@mail.acme.com`). Verifying the subdomain itself (`mail.acme.com`) is better practice for marketing mail because it keeps reputation separate from your transactional domain.

## Limits

| Plan | Domains |
|---|---|
| Free | 3 |
| Pro | 10 |
| Scale | 1,000 |

Adding a domain that another team already registered returns `422 validation_error` ("Domain already registered").

## DNS provider guides

  
  
  
  
  
  
  
  

Stuck? See [Troubleshooting](/domains/troubleshooting/).

---

# DMARC

URL: https://docs.spacepost.dev/domains/dmarc/

DMARC tells receiving servers what to do when a message claiming to be from your domain fails SPF and DKIM alignment, and where to send reports. Gmail and Yahoo require it from anyone sending in volume, and it protects your domain from spoofing.

SpacePost returns a recommended starter record with every domain:

| Type | Name | Value |
|---|---|---|
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

It is not required for verification, but add it.

## How alignment works with SpacePost

- **DKIM**: messages are signed with `d=acme.com` via your three Easy DKIM CNAMEs. This aligns with `From: hello@acme.com`.
- **SPF**: the envelope sender (return path) is `send.acme.com`, a subdomain of your From domain, so SPF aligns in relaxed mode. This is why the `send` MX and TXT records matter.

Either one aligning is enough for DMARC to pass; having both is the most robust.

## Policies

| Policy | Effect | When |
|---|---|---|
| `p=none` | Monitor only. Nothing is blocked. | Start here. |
| `p=quarantine` | Failing mail goes to spam. | After reports are clean for a few weeks. |
| `p=reject` | Failing mail is rejected. | Full protection. |

A typical progression with reporting:

```text
v=DMARC1; p=none; rua=mailto:dmarc@acme.com; fo=1;
v=DMARC1; p=quarantine; pct=25; rua=mailto:dmarc@acme.com;
v=DMARC1; p=reject; rua=mailto:dmarc@acme.com;
```

`rua` is where aggregate XML reports go. Use a DMARC reporting service to read them.

> Note:
Before moving to `quarantine` or `reject`, make sure **every** system that sends as your domain (your marketing tool, support desk, CRM) is aligned. Otherwise you will block your own mail.

## Subdomains

A `_dmarc` record on `acme.com` also covers subdomains unless you add `sp=`. If you send from `mail.acme.com`, you can publish a separate `_dmarc.mail` record.

---

# Open and click tracking

URL: https://docs.spacepost.dev/domains/tracking/

Tracking is configured **per domain** and is **off by default**.

| Setting | What it does | Webhook event |
|---|---|---|
| `open_tracking` | Inserts a 1x1 tracking pixel into the HTML body. | `email.opened` |
| `click_tracking` | Rewrites links in the HTML body so clicks are recorded before redirecting. | `email.clicked` |

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.domains.update({
  id: "0192e1c4-0000-7000-8000-000000000001",
  openTracking: true,
  clickTracking: true,
});
if (error) console.error(error);
```
  
  **cURL**

    ```bash
    curl -X PATCH https://api.spacepost.dev/domains/$DOMAIN_ID \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{ "open_tracking": true, "click_tracking": true }'
    ```
  

The change applies to emails sent afterwards. Both fields are optional; send only the one you want to change.

## Considerations

- **Opens are approximate.** Apple Mail Privacy Protection and some security scanners load images automatically, inflating opens. Gmail caches images. Treat opens as a rough signal, never as proof a person read the email.
- **Clicks are more reliable** but security scanners can also pre-click links.
- **Privacy.** Tracking records IP address and user agent in the event payload. Disclose it in your privacy policy, and consider leaving open tracking off for sensitive transactional mail (password resets, receipts).
- **Plain-text parts are never tracked.** Tracking only affects HTML.
- **Deliverability.** Link rewriting changes the URLs recipients see. Some spam filters dislike this on transactional mail; if you see a deliverability dip, turn click tracking off for that domain and use a separate subdomain for marketing mail.

An `email.opened` or `email.clicked` event sets the email's `last_event`, but never moves it backwards from a more severe state such as `bounced`.

---

# Custom return path

URL: https://docs.spacepost.dev/domains/return-path/

The **return path** (also called MAIL FROM or envelope sender) is where bounces are sent. By default SpacePost uses the `send` subdomain: `send.acme.com`. It gets an MX record, so bounce notifications reach Amazon SES, and an SPF TXT record.

Using your own subdomain instead of Amazon's default means SPF is evaluated against **your** domain, so it aligns with your `From` address for DMARC.

## Change the subdomain

Set `custom_return_path` when you add the domain. It must be 1 to 63 characters of lowercase letters, digits and hyphens.

  **Node.js**

```ts
await spacepost.domains.create({ name: "acme.com", customReturnPath: "bounces" });
```
  
  **cURL**

```bash
curl -X POST https://api.spacepost.dev/domains \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "acme.com", "custom_return_path": "bounces" }'
```
  

The returned MX and TXT records then use the name `bounces` instead of `send`.

> Note:
The return path is fixed when the domain is created. To change it later, delete the domain and add it again, then update your DNS.

## Pick a name that is not in use

The return-path subdomain must not already have other MX or TXT records you rely on (for example, a support tool using `send.acme.com`). Choose something unique such as `bounces` or `pk-send`.

---

# Domain troubleshooting

URL: https://docs.spacepost.dev/domains/troubleshooting/

Start with the CLI, which looks up every record live:

```bash
spacepost domains doctor acme.com
```

Or compare by hand with `dig`:

```bash
dig +short CNAME a1b2c3d4e5f6._domainkey.acme.com
dig +short MX send.acme.com
dig +short TXT send.acme.com
dig +short TXT _dmarc.acme.com
```

## The domain stays `pending` or `not_started`

| Cause | Fix |
|---|---|
| Records not created yet, or DNS has not propagated | Wait 10 to 30 minutes, then call `POST /domains/{id}/verify`. TTLs of an hour or more can delay it. |
| **Domain name doubled** (`a1b2._domainkey.acme.com.acme.com`) | Your DNS provider appends the domain automatically; enter only the relative name (`a1b2._domainkey`). Check with `dig`. |
| **Name missing the domain** (`a1b2._domainkey` is unresolvable) | Your provider needs the full name (`a1b2._domainkey.acme.com`), common with Route 53. |
| **Cloudflare proxy on** | CNAME records for DKIM must be **DNS only** (grey cloud), not proxied. |
| Trailing dot or stray whitespace in the value | Re-paste the value exactly. |
| Quotes around TXT value | Enter the value without quotes. |
| Conflicting existing record on `send` | A CNAME on `send.acme.com` cannot coexist with MX/TXT. Use a different [custom return path](/domains/return-path/). |
| Two SPF records on the same name | Merge them into one TXT value. Only one `v=spf1` record per name is allowed. |

## The domain turned `failed`

SpacePost gives up on a domain whose DNS has not appeared after **72 hours**. Fix the records, then call verify again; the status returns to `pending` and then `verified`.

## `invalid_from_address`

`403 invalid_from_address`: "The example.com domain is not verified." The domain in `from` must be a verified domain on **your team**, or a subdomain of one. Check for typos and for the wrong team's API key.

## `Domain already registered`

A domain can belong to only one team. If you re-registered a domain after leaving an old team, delete it there first or contact support.

## Return path verified but DMARC fails

Open a received message's headers (Gmail: Show original) and check `Authentication-Results`. You want `dkim=pass header.d=acme.com` and `spf=pass` with `smtp.mailfrom=send.acme.com`. If SPF shows `amazonses.com`, the return-path records are missing or not yet verified.

## Still stuck

Email [support@spacepost.dev](mailto:support@spacepost.dev) with the domain name and the output of `spacepost domains doctor`.

---

# Webhooks overview

URL: https://docs.spacepost.dev/webhooks/overview/

Webhooks push email events to your server as they happen, so you do not have to poll `GET /emails/{id}`. SpacePost signs every request with the [Standard Webhooks](https://www.standardwebhooks.com) scheme (the one Svix and Resend use), so existing verification code works unchanged.

1. **Create an endpoint** that accepts `POST` with a JSON body and answers `2xx` quickly.

2. **Register it**

   
     **Node.js**

       ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: webhook, error } = await spacepost.webhooks.create({
  endpoint: "https://acme.com/webhooks/spacepost",
  events: ["email.delivered", "email.bounced", "email.complained"],
});
if (error) throw new Error(`${error.name}: ${error.message}`);

// Store this secret: you need it to verify signatures. It starts with "whsec_".
console.log(webhook.id, webhook.signing_secret);
```
     
     **cURL**

       ```bash
       curl -X POST https://api.spacepost.dev/webhooks \
         -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
         -d '{
           "endpoint": "https://acme.com/webhooks/spacepost",
           "events": ["email.delivered", "email.bounced", "email.complained"]
         }'
  ```

**Python**

  ```python
       r = requests.post(
           "https://api.spacepost.dev/webhooks",
           headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
           json={"endpoint": "https://acme.com/webhooks/spacepost", "events": ["email.delivered", "email.bounced"]},
       )
       print(r.json()["signing_secret"])
       ```
     
   

```json title="Response"
{
  "object": "webhook",
  "id": "0192e1c4-0000-7000-8000-0000000000aa",
  "endpoint": "https://acme.com/webhooks/spacepost",
  "events": ["email.delivered", "email.bounced", "email.complained"],
  "status": "enabled",
  "created_at": "2026-10-23T14:00:00.000Z",
  "signing_secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
```

3. **Verify the signature** on every request. See [Verifying signatures](/webhooks/verifying/).

4. **Return `2xx`.** Anything else (including redirects and timeouts) is retried. See [Retries](/webhooks/retries/).

## Request format

Every delivery is a `POST` with `Content-Type: application/json` and these headers:

| Header | Value |
|---|---|
| `webhook-id` | Unique id of this delivery. **The same id on every retry**, so use it to deduplicate. |
| `webhook-timestamp` | Unix time in seconds when this attempt was sent. |
| `webhook-signature` | `v1,<base64 HMAC-SHA256>`. A space-separated list if there are several signatures. |
| `svix-id`, `svix-timestamp`, `svix-signature` | Identical duplicates of the three headers above, so Svix libraries work as is. |

The body is `{ "type": "...", "created_at": "...", "data": { ... } }`. See [Event types](/webhooks/event-types/).

## Managing webhooks

`POST /webhooks`, `GET /webhooks`, `GET /webhooks/{id}`, `PATCH /webhooks/{id}` (change `endpoint`, `events` or `status`: `enabled` or `disabled`) and `DELETE /webhooks/{id}`. The `signing_secret` is returned when you create or fetch a single webhook, not in lists.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
const id = "0192e1c4-0000-7000-8000-0000000000aa";

// Subscribe to more events and temporarily disable delivery.
await spacepost.webhooks.update({ id, events: ["email.delivered", "email.bounced", "email.opened"], status: "disabled" });

const { data } = await spacepost.webhooks.list({ limit: 20 });
console.log(data?.data.map((w) => `${w.id} ${w.status} ${w.endpoint}`));

await spacepost.webhooks.remove(id);
```

## Requirements for endpoints

- `https://` in production (plain `http://` is accepted only in development).
- The host must resolve to a **public** address. Localhost and private networks are rejected. For local development use a tunnel such as ngrok or Cloudflare Tunnel.
- Respond within **15 seconds**.
- Redirects are not followed.

---

# Event types

URL: https://docs.spacepost.dev/webhooks/event-types/

Subscribe to any combination of these event types when you create a webhook.

| Event | Fires when | Sets `last_event` to |
|---|---|---|
| `email.scheduled` | An email with `scheduled_at` was accepted. | `scheduled` |
| `email.sent` | The email was handed to Amazon SES. | `sent` |
| `email.delivered` | The recipient's mail server accepted the email. | `delivered` |
| `email.delivery_delayed` | Delivery is delayed or temporarily failing; SES keeps retrying. | `delivery_delayed` |
| `email.bounced` | Permanent failure (the address does not exist, domain rejects). | `bounced` |
| `email.complained` | The recipient marked the email as spam. | `complained` |
| `email.opened` | The recipient opened the email (needs [open tracking](/domains/tracking/)). | `opened` |
| `email.clicked` | The recipient clicked a link (needs [click tracking](/domains/tracking/)). | `clicked` |
| `email.failed` | SpacePost or SES could not send the email (rejected, rendering failure, paused team or tenant). | `failed` |
| `email.suppressed` | A recipient was skipped because it is on your [suppression list](/deliverability/bounces-and-complaints/). | `suppressed` |

## Payload shape

Webhook bodies are exactly [Resend's](https://resend.com/docs/dashboard/webhooks/event-types), so handlers written for Resend keep working.

```json
{
  "type": "email.delivered",
  "created_at": "2026-10-23T14:02:10.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z",
    "broadcast_id": "0192e1c4-0000-7000-8000-0000000000bb",
    "tenant_id": "0192e1c4-5555-7000-8000-0000000000cc",
    "tags": { "category": "welcome" }
  }
}
```

- `type` is the event; `created_at` is when the event happened.
- `data.email_id`, `from`, `to` (all recipients of the email, not only the affected one), `subject` and `created_at` (when the email was created) are always present.
- `data.broadcast_id` is present only for [broadcast](/audiences/broadcasts/) emails.
- `data.tenant_id` is present only when the email was sent for a [tenant](/platform/tenants/) (platform mode). It is our tenant id, not your `external_id`.
- `data.tags` is present only if the email had tags, as an **object** (`{ "name": "value" }`).
- Some events add one more object to `data`, named after the event: `bounce`, `click`, `open`, `failed` or `suppressed`. They are listed below. Nothing else is added: there are no top-level `bounceType`, `delayType` or `reason` keys.

## Examples

### email.scheduled

```json
{
  "type": "email.scheduled",
  "created_at": "2026-10-23T14:02:09.700Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-23T14:02:09.512Z"
  }
}
```

### email.sent

```json
{
  "type": "email.sent",
  "created_at": "2026-10-23T14:02:10.100Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z"
  }
}
```

### email.delivered

```json
{
  "type": "email.delivered",
  "created_at": "2026-10-23T14:02:11.350Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z"
  }
}
```

### email.delivery_delayed

Fired for SES delivery delays and for transient bounces. There are no extra fields for a plain delay. A transient bounce also carries the `bounce` object (see below, with `type: "Transient"`).

```json
{
  "type": "email.delivery_delayed",
  "created_at": "2026-10-23T14:07:00.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z"
  }
}
```

### email.bounced

Only permanent bounces reach this event, and they add the address to your suppression list. `data.bounce` has `type` (`Permanent`), `subType` and the receiving server's `message`.

```json
{
  "type": "email.bounced",
  "created_at": "2026-10-23T14:02:12.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["nobody@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z",
    "bounce": {
      "type": "Permanent",
      "subType": "General",
      "message": "smtp; 550 5.1.1 The email account that you tried to reach does not exist."
    }
  }
}
```

Bounce sub types include `General`, `NoEmail`, `Suppressed`, `OnAccountSuppressionList`, `MailboxFull`, `MessageTooLarge`, `ContentRejected` and `AttachmentRejected`.

### email.complained

No extra fields. The address is added to your suppression list.

```json
{
  "type": "email.complained",
  "created_at": "2026-10-23T15:30:00.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Our monthly newsletter",
    "created_at": "2026-10-23T14:02:09.512Z"
  }
}
```

### email.opened

```json
{
  "type": "email.opened",
  "created_at": "2026-10-23T14:05:44.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z",
    "open": { "ipAddress": "203.0.113.7", "userAgent": "Mozilla/5.0 (Macintosh)" }
  }
}
```

### email.clicked

```json
{
  "type": "email.clicked",
  "created_at": "2026-10-23T14:06:10.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z",
    "click": {
      "link": "https://acme.com/get-started",
      "ipAddress": "203.0.113.7",
      "userAgent": "Mozilla/5.0 (Macintosh)",
      "timestamp": "2026-10-23T14:06:10.000Z"
    }
  }
}
```

### email.failed

```json
{
  "type": "email.failed",
  "created_at": "2026-10-23T14:02:10.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z",
    "failed": { "reason": "Attachment https://files.acme.com/report.pdf returned HTTP 404" }
  }
}
```

### email.suppressed

`suppressed.reason` is `suppression_list` (the recipient is on your [suppression list](/deliverability/bounces-and-complaints/)) or `recipient_domain_does_not_accept_mail` (the recipient's domain has no mail server).

```json
{
  "type": "email.suppressed",
  "created_at": "2026-10-23T14:02:10.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com", "other@example.com"],
    "subject": "Welcome to Acme",
    "created_at": "2026-10-23T14:02:09.512Z",
    "suppressed": { "recipients": ["other@example.com"], "reason": "suppression_list" }
  }
}
```

> Note:
`data.to` always lists **all** recipients of the email. For multi-recipient emails, use the delivery events together with your own records to work out who was affected. `suppressed.recipients` names the skipped addresses.

## Typing events in TypeScript

The Node SDK exports a `WebhookPayload` union discriminated by `type`, and `spacepost.webhooks.verify()` returns it, so narrowing on `event.type` gives you the right `data` fields:

```ts

function handle(event: WebhookPayload) {
  switch (event.type) {
    case "email.bounced":
      return event.data.bounce?.subType;
    case "email.clicked":
      return event.data.click?.link;
    case "email.suppressed":
      return event.data.suppressed.recipients;
    case "email.failed":
      return event.data.failed.reason;
    default:
      return event.data.tenant_id; // present when the email was sent for a tenant
  }
}
```

---

# Verifying signatures

URL: https://docs.spacepost.dev/webhooks/verifying/

Anyone who learns your endpoint URL can post to it. Always verify the signature before trusting a payload.

## How signing works

Each delivery carries:

```text
webhook-id:        0192e1c4-0000-7000-8000-0000000000cc
webhook-timestamp: 1761228131
webhook-signature: v1,K5oZfzN0mYI+Hx3Yb0v8j3H5kq2tqZ2dA8s0r6sF9Vw=
```

The signature is the base64 **HMAC-SHA256** of `"{webhook-id}.{webhook-timestamp}.{raw body}"`, keyed with the secret's bytes: take your `signing_secret`, drop the `whsec_` prefix and base64-decode the rest. Reject requests whose timestamp is more than 5 minutes from your clock to stop replays.

> Note:
Verify against the **raw request body** exactly as received. If a framework parses and re-serializes the JSON first, the signature will not match.

  **Node.js**

    The SpacePost SDK verifies with WebCrypto and returns the parsed event. It throws if the signature or timestamp is invalid.

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

/** Works as a Bun, Deno, Cloudflare Workers or Next.js route handler. */
export async function POST(request: Request): Promise<Response> {
  const payload = await request.text(); // the RAW body: do not parse it first

  try {
    const event = await spacepost.webhooks.verify({
      payload,
      headers: request.headers,
      secret: process.env.SPACEPOST_WEBHOOK_SECRET!,
    });

    switch (event.type) {
      case "email.bounced":
      case "email.complained":
        console.warn("Stop mailing", event.data.to);
        break;
      case "email.delivered":
        console.log("Delivered", event.data.email_id);
        break;
    }
    return new Response("ok");
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
}
```

    Headers can be a `Headers` object or a plain object (for example Express' `req.headers`). With Express, mount `express.raw({ type: "application/json" })` on the webhook route so `req.body` is a Buffer.

    **With the `standardwebhooks` package:**

    ```ts
    import { Webhook } from "standardwebhooks";

    const wh = new Webhook(process.env.SPACEPOST_WEBHOOK_SECRET!); // "whsec_..." is accepted
    const event = wh.verify(rawBody, {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
    });
```

**With `svix`** (or the `resend` package's verifier): use the `svix-*` headers, which SpacePost also sends.

```ts
    import { Webhook } from "svix";

    const wh = new Webhook(process.env.SPACEPOST_WEBHOOK_SECRET!);
    const event = wh.verify(rawBody, {
      "svix-id": req.headers["svix-id"] as string,
      "svix-timestamp": req.headers["svix-timestamp"] as string,
      "svix-signature": req.headers["svix-signature"] as string,
    });
  ```

**Python**

  ```bash
    pip install standardwebhooks
```
```python
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
wh = Webhook(os.environ["SPACEPOST_WEBHOOK_SECRET"])  # "whsec_..." is accepted

@app.post("/webhooks/spacepost")
def spacepost_webhook():
    try:
        event = wh.verify(request.get_data(as_text=True), dict(request.headers))
    except WebhookVerificationError:
        return "invalid signature", 400
    print(event["type"], event["data"]["email_id"])
    return "", 200
```

    Without a library:

```python
import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes, tolerance: int = 300) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(s.split(",", 1)[1], expected)
               for s in headers["webhook-signature"].split() if s.startswith("v1,"))
```
  
  **Go**

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"io"
	"math"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

func verify(secret string, h http.Header, body []byte) bool {
	id := h.Get("webhook-id")
	ts := h.Get("webhook-timestamp")
	n, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-n)) > 300 {
		return false
	}
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + ts + "."))
	mac.Write(body)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	for _, s := range strings.Fields(h.Get("webhook-signature")) {
		if v, ok := strings.CutPrefix(s, "v1,"); ok && hmac.Equal([]byte(v), []byte(expected)) {
			return true
		}
	}
	return false
}

func main() {
	http.HandleFunc("/webhooks/spacepost", func(w http.ResponseWriter, r *http.Request) {
		body, _ := io.ReadAll(r.Body)
		if !verify(os.Getenv("SPACEPOST_WEBHOOK_SECRET"), r.Header, body) {
			http.Error(w, "invalid signature", http.StatusBadRequest)
			return
		}
		fmt.Println("event:", string(body))
		w.WriteHeader(http.StatusOK)
	})
	http.ListenAndServe(":8080", nil)
}
```

    Or use the official library: `go get github.com/standard-webhooks/standard-webhooks/libraries/go` and call `wh, _ := standardwebhooks.NewWebhook(secret); err := wh.Verify(body, r.Header)`.
  
  **PHP**

```php
<?php
function verify_spacepost_webhook(string $secret, array $headers, string $body, int $tolerance = 300): bool {
    $headers = array_change_key_case($headers, CASE_LOWER);
    $id = $headers['webhook-id'] ?? '';
    $ts = $headers['webhook-timestamp'] ?? '';
    if (!ctype_digit($ts) || abs(time() - (int) $ts) > $tolerance) {
        return false;
    }
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $key, true));
    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $sig) {
        if (str_starts_with($sig, 'v1,') && hash_equals($expected, substr($sig, 3))) {
            return true;
        }
    }
    return false;
}

$body = file_get_contents('php://input');
if (!verify_spacepost_webhook(getenv('SPACEPOST_WEBHOOK_SECRET'), getallheaders(), $body)) {
    http_response_code(400);
    exit('invalid signature');
}
$event = json_decode($body, true);
error_log($event['type'] . ' ' . $event['data']['email_id']);
http_response_code(200);
```
  

## Using the Resend SDK's verifier

The official `resend` package's webhook verification takes the same Standard Webhooks headers, so it works with your SpacePost `signing_secret`.

## Rotating secrets

The `signing_secret` is fixed per webhook. To rotate, create a new webhook with the same endpoint, switch your handler to accept the new secret (try both during the changeover), then delete the old webhook.

## Testing locally

Send an email to `delivered@test.spacepost.dev` with a tunnel URL registered as your endpoint. See [Testing](/sending/testing/).

---

# Retries

URL: https://docs.spacepost.dev/webhooks/retries/

A delivery succeeds when your endpoint answers with a `2xx` status within **15 seconds**. Anything else (a non-2xx status, a redirect, a timeout, a connection error, a TLS error) is a failure and is retried.

## Schedule

SpacePost makes up to **8 attempts**: the first immediately, then retries with increasing delays after each failure.

| Attempt | Delay after the previous failure | Roughly after the event |
|---|---|---|
| 1 | immediate | 0 |
| 2 | 5 seconds | 5 s |
| 3 | 5 minutes | 5 min |
| 4 | 30 minutes | 35 min |
| 5 | 2 hours | 2 h 35 min |
| 6 | 5 hours | 7 h 35 min |
| 7 | 10 hours | 17 h 35 min |
| 8 | 10 hours | 27 h 35 min |

After the 8th failed attempt the delivery is marked **failed** and no further automatic attempts are made. You can [replay](/webhooks/replay/) it manually.

## Things to know

- **The `webhook-id` is the same on every attempt**, and the body is identical. The `webhook-timestamp` and signature are regenerated for each attempt.
- **Delivery is at least once.** A slow `2xx` that arrives after the timeout is treated as a failure, so your endpoint may see the same event twice. Deduplicate on `webhook-id`.
- **Ordering is not guaranteed.** A retried `email.delivered` can arrive after a later `email.opened`. Use `created_at` in the payload and never move an email's state backwards.
- **Disabled or deleted webhooks** stop receiving deliveries; pending deliveries for them are marked failed.
- Response bodies (first 1 KB) and status codes of recent attempts are visible in the dashboard delivery log, which keeps 30 days of history.

> Note:
Return `200` as soon as you have verified the signature and stored the event. Do slow work in a background job. A handler that takes more than 15 seconds will be retried and cause duplicate work.

---

# Webhook best practices

URL: https://docs.spacepost.dev/webhooks/best-practices/

## Respond fast, process later

Verify the signature, enqueue the event (database row, queue, background job) and return `2xx` immediately. SpacePost waits at most 15 seconds, and a slow handler turns into retries and duplicates.

## Be idempotent

Delivery is at least once. Store the `webhook-id` of each processed delivery (a unique constraint is enough) and skip repeats.

```ts
const inserted = await db.insert(processedWebhooks).values({ id: webhookId }).onConflictDoNothing().returning();
if (inserted.length === 0) return new Response("duplicate", { status: 200 });
```

## Always verify signatures

Use the raw body, reject timestamps older than 5 minutes, compare signatures in constant time (the SDK and libraries do). See [Verifying signatures](/webhooks/verifying/).

## Do not trust order

Events can arrive out of order, especially after retries. Compare the payload's `created_at` with what you have stored, and only apply changes that move state forward. SpacePost's own `last_event` follows the same rule.

## Act on the events that matter

| Event | Typical action |
|---|---|
| `email.bounced` | Mark the address invalid in your database; stop sending to it. |
| `email.complained` | Unsubscribe the user from non-essential mail immediately. |
| `email.delivery_delayed` | Usually nothing; alert if it is a time-critical email (password reset). |
| `email.failed` | Log `data.failed.reason`, alert, possibly retry with a fix. |
| `email.suppressed` | A recipient was on your suppression list; show it in your admin UI. |

Subscribe only to the events you handle. Fewer events means less traffic and fewer failures.

## Secure the endpoint

- Serve over HTTPS with a valid certificate.
- Do not log secrets or full payloads containing personal data.
- Use a dedicated path with no other behavior and return a generic body.
- Keep the `signing_secret` in a secret manager, not in source control.

## Monitor

Watch the dashboard delivery log or alert on repeated failures: if your endpoint is down for more than about 27 hours all retries are used up, after which you must [replay](/webhooks/replay/) manually.

---

# Platform mode (tenants)

URL: https://docs.spacepost.dev/platform/tenants/

Platform mode lets one SpacePost account send for many of **your customers**. Each customer is a **tenant**. Use it when you build a product that sends email for other businesses, for example an invoicing or support SaaS where every customer connects their own domain and one bad actor must not hurt everybody else.

If you only send your own product's email, you do not need tenants.

## What a tenant gives you

| | |
|---|---|
| **Isolated reputation** | Every tenant gets its own Amazon SES tenant. Complaints and bounces from one customer show up on that customer only. |
| **Its own reputation guard** | The same [automatic pausing](/deliverability/auto-pausing/) thresholds (over 5% bounces or 0.2% complaints across the tenant's last 1,000 emails, with minimum sample sizes) pause **only that tenant**. |
| **Your account stays clean** | Tenant mail does not count toward your own team's reputation check, so one bad customer cannot pause your account or your other customers. |
| **Pause switch** | Pause and resume any tenant yourself, with a reason. |
| **Daily cap** | Optional `daily_limit` in recipients per UTC day, per tenant. |
| **Your IDs** | Address a tenant by your own `external_id` instead of storing ours. |
| **Attribution** | Emails, domains and [webhook events](/webhooks/event-types/) carry `tenant_id`. |

Tenants share your plan: every tenant recipient counts toward your [monthly quota](/account/plans-and-quotas/), your team's daily limits and your API rate limit. Content filtering applies to tenant mail too, including tenants of an account that is otherwise exempt from it.

## Create a tenant

`POST /tenants` takes a `name` and optionally an `external_id` (unique within your account) and a `daily_limit`. All tenant endpoints need a `full_access` API key.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

// One tenant per customer. `externalId` is your own customer id and works anywhere a tenant id does.
const { data: tenant, error } = await spacepost.tenants.create({
  name: "Acme Inc",
  externalId: "cust_123",
  dailyLimit: 500, // optional cap, in recipients per UTC day
});
if (error) throw new Error(`${error.name}: ${error.message}`);
console.log(tenant.id, tenant.status); // "active"

// Optional: give the tenant its own sending domain. Mail from it is attributed to the tenant automatically.
const { data: domain } = await spacepost.domains.create({ name: "mail.acme-inc.com", tenantId: "cust_123" });
console.log(domain?.tenant_id === tenant.id); // true
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/tenants \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Acme Inc", "external_id": "cust_123", "daily_limit": 500 }'
  ```

**CLI**

  ```bash
    spacepost tenants create --name "Acme Inc" --external-id cust_123 --daily-limit 500
    ```
  

```json title="Response"
{
  "object": "tenant",
  "id": "0192e1c4-5555-7000-8000-0000000000cc",
  "name": "Acme Inc",
  "external_id": "cust_123",
  "daily_limit": 500,
  "status": "active",
  "paused_reason": null,
  "created_at": "2026-10-23T14:02:09.512Z"
}
```

### `external_id`

Everywhere a tenant is addressed (`/tenants/:ref`, `tenant_id` on emails and domains, `spacepost tenants get <ref>`) you can pass either our `id` or your `external_id`. Store your own customer id once and you never need to keep a mapping table. Webhooks always carry **our** tenant id; look it up with `GET /tenants/{id}` if you need the `external_id`.

## Domains: tenant-owned or team-level

| | Tenant-owned domain | Team-level domain |
|---|---|---|
| Created with | `tenant_id` on `POST /domains` | `POST /domains` without `tenant_id` |
| Typical owner | The customer's own domain (`mail.acme-inc.com`) | Your domain (`yourapp.com`) |
| Attribution | Automatic: every email from it belongs to the tenant | You pass `tenant_id` on each email, or the email is your own |
| Who may send from it | Only that tenant | Your own mail, and any tenant |

If an email names a `tenant_id` that differs from its domain's tenant, the request fails with `422 validation_error`. A `tenant_id` is optional when the `from` domain already belongs to a tenant.

Add a tenant-owned domain exactly like any domain, with one extra field, then add the DNS records at the customer's DNS provider. See [Adding and verifying](/domains/adding-and-verifying/).

  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/domains \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "mail.acme-inc.com", "tenant_id": "cust_123" }'
  ```

**CLI**

  ```bash
    spacepost domains add mail.acme-inc.com --tenant cust_123
    ```
  

## Send for a tenant

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

// From a team-level domain (yours), name the tenant on each email.
const { data, error } = await spacepost.emails.send({
  from: "Acme Inc via YourApp <invoices@yourapp.com>",
  to: "buyer@example.com",
  subject: "Invoice #1042",
  html: "<p>Your invoice is attached.</p>",
  tenantId: "cust_123", // our tenant id or your external_id
});

if (error?.name === "sending_paused") {
  console.warn("This customer is paused:", error.message);
} else if (error?.name === "daily_quota_exceeded") {
  console.warn("This customer hit its daily cap; retry tomorrow.");
} else if (error) {
  throw new Error(`${error.name}: ${error.message}`);
} else {
  console.log("Queued", data.id);
}

// batch.send accepts tenantId per email.
await spacepost.batch.send([
  { from: "invoices@yourapp.com", to: "a@example.com", subject: "Hello A", text: "Hi A", tenantId: "cust_123" },
  { from: "invoices@yourapp.com", to: "b@example.com", subject: "Hello B", text: "Hi B", tenantId: "cust_456" },
]);
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/emails \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "from": "Acme Inc via YourApp <invoices@yourapp.com>",
        "to": ["buyer@example.com"],
        "subject": "Invoice #1042",
        "html": "<p>Your invoice is attached.</p>",
        "tenant_id": "cust_123"
      }'
    ```

    `POST /emails/batch` accepts `tenant_id` on each item.
  
  **Resend SDK**

    The official `resend` package works against SpacePost unchanged. Point it at us with `RESEND_BASE_URL=https://api.spacepost.dev` or `new Resend(key, { baseUrl })`.

    **Easiest: send from a tenant-owned domain.** The tenant is inferred from the `from` domain, so your existing `resend.emails.send` calls need no change at all.

    **From a team-level domain, use `resend.post`.** The Resend SDK builds the request body from a fixed list of fields, so an extra `tenant_id` passed to `resend.emails.send`, `resend.batch.send` or `resend.domains.create` is silently dropped before it reaches SpacePost. `resend.post` sends the body you give it as is, so use it with snake_case fields:

    ```ts
    import { Resend } from "resend";

    const resend = new Resend(process.env.SPACEPOST_API_KEY, { baseUrl: "https://api.spacepost.dev" });

    const { data, error } = await resend.post<{ id: string }>("/emails", {
      from: "Acme Inc via YourApp <invoices@yourapp.com>",
      to: ["buyer@example.com"],
      subject: "Invoice #1042",
      html: "<p>Your invoice is attached.</p>",
      tenant_id: "cust_123",
    });
    ```

    Unlike `resend.emails.send`, `resend.post` does not convert camelCase: write `reply_to` and `scheduled_at`. The same works for `resend.post("/domains", { name, tenant_id })` and `resend.post("/emails/batch", [...])`.

    > Note:
    Type definitions of the Resend SDK do not know `tenant_id`, so passing it to `emails.send` also needs a cast (`as never`) in TypeScript, and it would still be dropped at runtime. Prefer `resend.post` or tenant-owned domains. `@spacepost/node` supports `tenantId` natively.
    
  
  **CLI**

    ```bash
    spacepost send --from invoices@yourapp.com --to buyer@example.com \
      --subject "Invoice #1042" --text "Your invoice is attached." --tenant cust_123
    ```
  

## Pause, resume and caps

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: page } = await spacepost.tenants.list({ limit: 20 });
for (const t of page?.data ?? []) console.log(t.name, t.external_id, t.status, t.paused_reason);

await spacepost.tenants.get("cust_123"); // by external_id or our id
await spacepost.tenants.update({ id: "cust_123", dailyLimit: 1000 }); // dailyLimit: null removes the cap

await spacepost.tenants.pause({ id: "cust_123", reason: "Investigating spam reports" });

const { error } = await spacepost.tenants.unpause("cust_123");
if (error?.statusCode === 403) console.warn("Paused by the reputation guard; contact support to review it.");

// Domains first, then the tenant (422 while it still has domains).
const { data: domains } = await spacepost.domains.list({ limit: 100 });
for (const d of domains?.data ?? []) if (d.tenant_id) console.log(d.name, "belongs to", d.tenant_id);
await spacepost.tenants.remove("cust_123");
```
  
  **cURL**

```bash
# Pause (the body is optional)
curl -X POST https://api.spacepost.dev/tenants/cust_123/pause \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "reason": "Investigating spam reports" }'

# Resume
curl -X POST https://api.spacepost.dev/tenants/cust_123/unpause -H "Authorization: Bearer $SPACEPOST_API_KEY"

# Change the cap (null removes it)
curl -X PATCH https://api.spacepost.dev/tenants/cust_123 \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "daily_limit": 1000 }'

# Delete (422 while the tenant still has domains)
curl -X DELETE https://api.spacepost.dev/tenants/cust_123 -H "Authorization: Bearer $SPACEPOST_API_KEY"
```
  
  **CLI**

```bash
spacepost tenants list
spacepost tenants get cust_123
spacepost tenants pause cust_123 --reason "Investigating spam reports"
spacepost tenants unpause cust_123
spacepost tenants rm cust_123
```
  

| Situation | Result |
|---|---|
| Sending for a **paused** tenant | `403 sending_paused`. Emails already queued fail with an `email.failed` event. |
| Tenant over its `daily_limit` | `429 daily_quota_exceeded` (the day resets at 00:00 UTC). Nothing from that request is sent. |
| `tenant_id` conflicts with the domain's tenant | `422 validation_error` |
| Unknown `tenant_id` | `404 not_found` |
| Unpausing a tenant paused by the reputation guard | `403 invalid_access`, unless your team is `trusted` or `internal`. Contact [support@spacepost.dev](mailto:support@spacepost.dev) after fixing the cause. Pauses you made yourself can always be lifted. |
| Deleting a tenant that still has domains | `422 validation_error`. Delete its domains first. |

> Note:
A tenant paused automatically by the reputation guard is a reputation signal for your whole account, which is why only reviewed teams can resume it themselves. Treat `paused_reason` ("Bounce rate 7.2% over the last 500 emails") as something to act on with the customer.

## Webhooks

Your normal [webhooks](/webhooks/overview/) receive events for tenant mail too, with `data.tenant_id` set to our tenant id. Emails without a tenant have no `tenant_id` key.

```json
{
  "type": "email.bounced",
  "created_at": "2026-10-23T14:02:12.000Z",
  "data": {
    "email_id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
    "from": "Acme Inc via YourApp <invoices@yourapp.com>",
    "to": ["nobody@example.com"],
    "subject": "Invoice #1042",
    "created_at": "2026-10-23T14:02:09.512Z",
    "tenant_id": "0192e1c4-5555-7000-8000-0000000000cc",
    "bounce": { "type": "Permanent", "subType": "General", "message": "smtp; 550 5.1.1 user unknown" }
  }
}
```

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

export async function handle(request: Request): Promise<Response> {
  const payload = await request.text();
  try {
    const event = await spacepost.webhooks.verify({
      payload,
      headers: request.headers,
      secret: process.env.SPACEPOST_WEBHOOK_SECRET!,
    });
    // `tenant_id` is our tenant id (not your external_id). It is absent on the team's own mail.
    const tenantId = event.data.tenant_id;
    if (event.type === "email.bounced" && tenantId) {
      console.log(`Bounce for tenant ${tenantId}: ${event.data.bounce?.subType}`);
    }
    return new Response("ok");
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
}
```

`GET /emails/{id}` and `GET /domains/{id}` also return `tenant_id` (or `null`), so you can reconcile in your own database.

## Checklist for a SaaS integration

1. Create a tenant when a customer signs up, with your customer id as `external_id`.
2. Decide per customer: their own domain (`tenant_id` on `POST /domains`) or your shared domain (`tenant_id` on every send).
3. Set a conservative `daily_limit` for new customers and raise it as they prove themselves.
4. Subscribe to `email.bounced`, `email.complained` and `email.failed`, and surface `tenant_id` problems in your admin UI.
5. Pause a customer yourself the moment you see abuse. It is instant and reversible.

---

# Audiences and contacts

URL: https://docs.spacepost.dev/audiences/contacts/

An **audience** is a list of **contacts** you can send [broadcasts](/audiences/broadcasts/) to. A contact belongs to exactly one audience; the same email address in two audiences is two contacts, each with its own unsubscribe state.

## Audiences

  **cURL**

```bash
curl -X POST https://api.spacepost.dev/audiences \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter" }'
```
```json title="Response"
{ "object": "audience", "id": "0192e1c4-0000-7000-8000-0000000000a1", "name": "Newsletter" }
```
  
  **Node.js**

```ts
const { data } = await spacepost.audiences.create({ name: "Newsletter" });
```
  

`GET /audiences`, `GET /audiences/{id}` and `DELETE /audiences/{id}` complete the set. Deleting an audience deletes its contacts. Audience names are 1 to 100 characters.

## Contacts

Contacts live under their audience: `/audiences/{audienceId}/contacts`.

- `email` (string, required): Unique within the audience. Stored lower-cased. Creating a duplicate returns `422`.
- `first_name` (string): Up to 100 characters. Used by `{{{FIRST_NAME}}}`.
- `last_name` (string): Up to 100 characters. Used by `{{{LAST_NAME}}}`.
- `unsubscribed` (boolean): Create the contact already unsubscribed (for example when importing a suppression list). Defaults to `false`.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: audience, error } = await spacepost.audiences.create({ name: "Newsletter" });
if (error) throw new Error(error.message);

// Create
await spacepost.contacts.create({
  audienceId: audience.id,
  email: "ada@example.com",
  firstName: "Ada",
  lastName: "Lovelace",
});

// Read by email (or by id)
const { data: contact } = await spacepost.contacts.get({ audienceId: audience.id, email: "ada@example.com" });
console.log(contact?.unsubscribed);

// Update
await spacepost.contacts.update({ audienceId: audience.id, email: "ada@example.com", firstName: "Augusta" });

// List, newest first
const { data: page } = await spacepost.contacts.list({ audienceId: audience.id, limit: 50 });
console.log(page?.data.length, page?.has_more);

// Unsubscribe manually, then delete
await spacepost.contacts.update({ audienceId: audience.id, email: "ada@example.com", unsubscribed: true });
await spacepost.contacts.remove({ audienceId: audience.id, email: "ada@example.com" });
```

  **cURL**

```bash
AUD=0192e1c4-0000-7000-8000-0000000000a1

# create
curl -X POST https://api.spacepost.dev/audiences/$AUD/contacts \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace" }'
# => { "object": "contact", "id": "..." }

# get by email (URL-encode the @) or by id
curl "https://api.spacepost.dev/audiences/$AUD/contacts/ada%40example.com" -H "Authorization: Bearer $SPACEPOST_API_KEY"

# update
curl -X PATCH "https://api.spacepost.dev/audiences/$AUD/contacts/ada%40example.com" \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "unsubscribed": true }'

# delete
curl -X DELETE "https://api.spacepost.dev/audiences/$AUD/contacts/ada%40example.com" -H "Authorization: Bearer $SPACEPOST_API_KEY"
```
  
  **Python**

```python
base = f"https://api.spacepost.dev/audiences/{audience_id}/contacts"
h = {"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"}

requests.post(base, headers=h, json={"email": "ada@example.com", "first_name": "Ada"})
requests.patch(f"{base}/ada@example.com", headers=h, json={"unsubscribed": True})
```
  

A contact looks like this:

```json
{
  "object": "contact",
  "id": "0192e1c4-0000-7000-8000-0000000000c1",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "created_at": "2026-10-23T14:00:00.000Z",
  "unsubscribed": false
}
```

`DELETE` returns `{ "object": "contact", "contact": "ada@example.com", "deleted": true }`. Where an `idOrEmail` is expected you can pass either the contact id or the email address.

## Unsubscribes

A contact with `unsubscribed: true` is skipped by every broadcast. Contacts unsubscribe themselves through the link in your emails ([Unsubscribe](/audiences/unsubscribe/)), and you can set the flag through the API when you learn about an opt-out elsewhere.

> Note:
Unsubscribing is per contact and only affects broadcasts. The [suppression list](/deliverability/bounces-and-complaints/) is team-wide and applies to **every** email, including transactional ones. Hard bounces and complaints add to it automatically.

## Importing

Import with a loop, respecting the [rate limit](/api/rate-limits/) (10 requests per second on Free and Pro):

```ts
for (const row of rows) {
  const { error } = await spacepost.contacts.create({ audienceId, email: row.email, firstName: row.first });
  if (error?.name === "rate_limit_exceeded") await new Promise((r) => setTimeout(r, 1000));
}
```

Only import people who agreed to hear from you. See [Compliance](/audiences/compliance/).

---

# Broadcasts

URL: https://docs.spacepost.dev/audiences/broadcasts/

A broadcast sends one message to every **subscribed** contact of an audience. SpacePost fans it out into one personalized email per contact, adds unsubscribe links and the `List-Unsubscribe` headers, skips suppressed addresses and tracks everything like any other email.

## Lifecycle

| Status | Meaning |
|---|---|
| `draft` | Created, editable, not sent. |
| `queued` | `send` was called; waiting for its start time (immediately, or `scheduled_at`). |
| `sending` | Being fanned out to contacts. |
| `sent` | Every email has been accepted for delivery. `sent_at` is set. |
| `failed` | Fan-out stopped, for example because a quota was reached or the team was paused. |
| `canceled` | Canceled before sending. |

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
const audienceId = "0192e1c4-0000-7000-8000-0000000000a1";

// 1. Create a draft
const { data: draft, error } = await spacepost.broadcasts.create({
  audienceId,
  name: "October newsletter",
  from: "Acme <news@acme.com>",
  replyTo: "support@acme.com",
  subject: "What's new at Acme, {{{FIRST_NAME|friend}}}",
  previewText: "Three things we shipped this month",
  html: `
    <h1>Hi {{{FIRST_NAME|there}}},</h1>
    <p>Here is what is new.</p>
    <p><a href="{{{SPACEPOST_UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>
  `,
});
if (error) throw new Error(error.message);

// 2. Send it now, or schedule it
const { error: sendError } = await spacepost.broadcasts.send(draft.id, { scheduledAt: "in 1 hour" });
if (sendError) throw new Error(sendError.message);

// 3. Check progress
const { data: broadcast } = await spacepost.broadcasts.get(draft.id);
console.log(broadcast?.status); // "queued" | "sending" | "sent" | "failed"
```

## Create a broadcast

`POST /broadcasts` creates a draft and returns `{ "id": "..." }`.

- `audience_id` (string (uuid), required): The audience to send to.
- `from` (string, required): Sender on a verified domain.
- `subject` (string, required): 1 to 998 characters. Placeholders are supported.
- `html` (string): HTML body. Provide `html`, `text` or both before sending.
- `text` (string): Plain-text body.
- `reply_to` (string | string[]): Up to 50 addresses.
- `preview_text` (string): Up to 200 characters. Shown after the subject in inboxes; inserted as a hidden preheader.
- `name` (string): Up to 100 characters. An internal label.

## Update and delete

`PATCH /broadcasts/{id}` accepts the same fields (all optional) and works **only on drafts**. `DELETE /broadcasts/{id}` works on drafts and on broadcasts that are scheduled for the future.

## Send

  **cURL**

```bash
# now
curl -X POST https://api.spacepost.dev/broadcasts/$ID/send -H "Authorization: Bearer $SPACEPOST_API_KEY"

# scheduled (ISO or natural language, up to 30 days ahead)
curl -X POST https://api.spacepost.dev/broadcasts/$ID/send \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-01T09:00:00Z" }'
```
  
  **Node.js**

```ts
await spacepost.broadcasts.send(id);                              // now
await spacepost.broadcasts.send(id, { scheduledAt: "in 1 hour" }); // later
```
  

Only drafts with an `html` or `text` body can be sent, from a verified domain. The response is `{ "id": "..." }`.

## Readiness checks

Before you send, `GET /broadcasts/{id}/readiness` returns a deliverability checklist (the dashboard shows the same list in the editor). It is a SpacePost extension and not part of Resend's API.

```json
{ "ready": true, "checks": [{ "id": "html_size", "level": "warn", "title": "Gmail will clip this message", "detail": "..." }] }
```

| Check | Level | When |
|---|---|---|
| `sender_domain` | error | The `from` domain is missing or not verified. |
| `dmarc` | warn | No `v=DMARC1` record at `_dmarc.<domain>`, or the lookup failed. `p=none` passes. |
| `subject` | error / warn | Error when empty. Warning for ALL CAPS, `!!!` or `$$$`, or more than 90 characters. |
| `html_size` | warn | HTML over 102 KB, which Gmail clips. |
| `images` | warn | Image-only, or four or more images with little text. |
| `shorteners` | warn | Links through bit.ly, tinyurl.com, t.co and similar. |
| `spam_phrases` | warn | Common spam wording in the subject or body. |
| `unsubscribe` | ok | An unsubscribe footer is added automatically when your body has no placeholder, so this never blocks. |
| `audience` | error | No subscribed contacts. |
| `role_addresses` | warn | More than 20% of contacts are addresses like `info@` or `admin@`. |

`ready` is `false` when any check has level `error`. Sending then fails with a `validation_error` (422) that lists what to fix. Warnings never block a send.

Broadcast emails also carry `List-Id` and `Feedback-ID` headers (`<broadcast id>:<team id>:broadcast:spacepost`) so Gmail Postmaster Tools can attribute complaints to a broadcast. Transactional emails do not.

## What a recipient gets

- **Personalization** is applied to `subject`, `html` and `text` ([Personalization](/audiences/personalization/)).
- **Unsubscribe:** if your body has no `{{{SPACEPOST_UNSUBSCRIBE_URL}}}` / `{{{RESEND_UNSUBSCRIBE_URL}}}` placeholder, an unsubscribe footer is appended automatically. The `List-Unsubscribe` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click` headers are always added.
- **Preview text** becomes a hidden preheader at the top of the HTML.
- Contacts that are unsubscribed, and addresses on your suppression list, are skipped.

## Quota and limits

Every recipient counts as one email against your plan quota, and the 100-per-day [sandbox](/deliverability/sandbox/) applies to new accounts. If the quota is exhausted mid-send the broadcast ends as `failed`; emails already created are still delivered. Fan-out is resumable if a worker restarts.

Each broadcast email is a normal email: it appears in `GET /emails`, carries `broadcast_id` in webhook payloads and can bounce or be opened.

> Note:
Send yourself a test first: create a one-contact audience containing your own address, create and send a broadcast to it, and check rendering and the unsubscribe flow.

---

# Personalization

URL: https://docs.spacepost.dev/audiences/personalization/

Broadcasts render each message per contact. Use triple braces in `subject`, `html` and `text`.

| Placeholder | Replaced with |
|---|---|
| `{{{FIRST_NAME}}}` | The contact's first name, or empty text if there is none. |
| `{{{FIRST_NAME\|fallback}}}` | The first name, or `fallback` when it is empty. |
| `{{{LAST_NAME}}}` | The contact's last name, or empty text. |
| `{{{EMAIL}}}` | The contact's email address. |
| `{{{SPACEPOST_UNSUBSCRIBE_URL}}}` | A signed, per-contact unsubscribe link. |
| `{{{RESEND_UNSUBSCRIBE_URL}}}` | Alias of the above, so templates migrated from Resend keep working. |

```html
<p>Hi {{{FIRST_NAME|there}}},</p>
<p>We sent this to {{{EMAIL}}}.</p>
<p><a href="{{{SPACEPOST_UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>
```

Subject example: `Welcome back, {{{FIRST_NAME|friend}}}`.

## Rules

- Whitespace inside the braces is ignored: `{{{ FIRST_NAME | there }}}` works.
- The fallback is trimmed and may contain spaces, but not `}`.
- Names are case-sensitive and uppercase.
- Values inserted into **HTML are escaped** (`<` becomes `&lt;`), so a contact named `<script>` cannot inject markup. In text bodies and subjects values are inserted as-is.
- Unknown placeholders are left untouched, so typos are visible in your test send.
- Placeholders only work in broadcasts. Transactional emails sent with `POST /emails` are not templated; build the string in your code.

> Note:
Always set a fallback for names: `Hi {{{FIRST_NAME|there}}}` reads far better than `Hi ,`.

---

# Unsubscribe

URL: https://docs.spacepost.dev/audiences/unsubscribe/

Every broadcast email gets two unsubscribe mechanisms, with nothing for you to configure.

## The link

`{{{SPACEPOST_UNSUBSCRIBE_URL}}}` expands to a URL like `https://app.spacepost.dev/u/<token>`. The token is signed per contact, so it cannot be guessed or changed.

- Opening the link shows a confirmation page ("Stop receiving emails at j***@example.com?"). A `GET` never unsubscribes anyone, so link scanners and mail security tools do not unsubscribe people by accident. The address is masked on the page.
- Pressing the button sends a `POST` that sets the contact's `unsubscribed` flag to `true`.

If your HTML has no unsubscribe placeholder, a footer with a link is appended for you (and a plain-text line in the text part). Put the placeholder in your own design to control the wording and position.

## The headers

SpacePost adds the headers Gmail and Yahoo require for bulk mail:

```text
List-Unsubscribe: <https://app.spacepost.dev/u/<token>>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

With these, Gmail and Apple Mail show a native **Unsubscribe** button next to the sender. A click makes the mail client `POST` to the URL, which unsubscribes the contact immediately, as specified in RFC 8058. This is much better for your reputation than recipients using the spam button.

## What happens after

- The contact is skipped by all future broadcasts to that audience.
- Nothing is sent to your webhooks for unsubscribes at the moment; read the `unsubscribed` flag from `GET /audiences/{id}/contacts/{idOrEmail}` or list contacts to sync your own database.
- To resubscribe someone who asks, `PATCH` the contact with `{ "unsubscribed": false }`. Only do this on an explicit request.

## Transactional email

Unsubscribe links are for marketing mail. Password resets, receipts and security notices do not need one. If you send marketing content through `POST /emails`, add the headers yourself (see [Custom headers](/sending/headers/)) and handle opt-outs on your side, or use broadcasts.

---

# Deliverability best practices

URL: https://docs.spacepost.dev/deliverability/best-practices/

Deliverability is mostly reputation: mailbox providers learn from how recipients react to your mail. SpacePost gives you the infrastructure; these habits protect the reputation.

## Checklist

**Authentication**

- [ ] Domain verified with all three DKIM records ([guide](/domains/adding-and-verifying/))
- [ ] Return-path (`send`) MX and TXT records verified so SPF aligns
- [ ] A DMARC record published, starting with `p=none` ([DMARC](/domains/dmarc/))
- [ ] Send from a domain you own, never a free mail address like `gmail.com`

**Lists**

- [ ] Only email people who opted in; confirm signups with a double opt-in if you can
- [ ] Never send to addresses you did not collect yourself
- [ ] Remove addresses that bounce (SpacePost suppresses hard bounces automatically)
- [ ] Stop emailing people who never open after several months
- [ ] Make unsubscribing obvious and instant

**Content**

- [ ] Always include a plain-text part (SpacePost generates one from HTML if you do not)
- [ ] A recognisable From name and a real Reply-To
- [ ] Subject lines that match the content; no all caps, no excessive punctuation
- [ ] Reasonable image-to-text ratio; no giant images as the only content
- [ ] Few links, to domains you control; avoid URL shorteners
- [ ] A physical address and unsubscribe link in marketing mail

**Practice**

- [ ] [Warm up](/deliverability/warming-up/) new domains gradually
- [ ] Use separate subdomains for transactional (`mail.acme.com`) and marketing (`news.acme.com`) mail
- [ ] Keep bounce rate under 2% and complaint rate under 0.1%
- [ ] Watch webhooks for `bounced` and `complained` and act on them
- [ ] Test with the [test addresses](/sending/testing/), never with fake addresses

## Targets

| Metric | Healthy | Automatic pause at |
|---|---|---|
| Bounce rate | below 2% | above 5% (at least 10 bounces) |
| Complaint rate | below 0.1% | above 0.2% (at least 3 complaints) |

Rates are measured over your last 1,000 emails. See [Automatic pausing](/deliverability/auto-pausing/).

---

# Bounces, complaints and suppressions

URL: https://docs.spacepost.dev/deliverability/bounces-and-complaints/

## Bounces

| Type | Meaning | Event | Result |
|---|---|---|---|
| **Hard (permanent)** | The address does not exist or the domain rejects mail permanently. | `email.bounced` | `last_event` becomes `bounced`; the address is **added to your suppression list**. |
| **Soft (transient)** | A temporary problem such as a full mailbox or a server outage. SES keeps retrying. | `email.delivery_delayed` | Nothing is suppressed at first. After **3 soft bounces on different emails within 30 days**, the address is added to your suppression list. |

Hard bounces include `bounce.type: "Permanent"` and a `bounce.subType` in the [webhook payload](/webhooks/event-types/).

An address that keeps soft-bouncing is usually abandoned, and mailbox providers count repeated attempts against you. Soft bounces caused by the message rather than the address (message too large, content or attachment rejected) don't count toward the limit; fix the message instead.

## Complaints

A complaint happens when a recipient marks your email as spam and their mailbox provider reports it back (a feedback loop). SpacePost raises `email.complained`, sets `last_event` to `complained` and **adds the recipient to your suppression list**. Complaints are the strongest negative signal there is: keep them below 0.1%.

## The suppression list

The suppression list is a per-team do-not-send list. Before every send SpacePost checks all recipients (`to`, `cc`, `bcc`) against it:

- Suppressed recipients are **removed** from the message and an `email.suppressed` event is raised.
- If no recipient is left, nothing is sent and the email's `last_event` is `suppressed`.
- Quota is counted when the email is accepted, before the suppression check, so suppressed recipients still count toward your monthly quota.

Entries are added automatically for hard bounces, repeated soft bounces and complaints, or manually with the API. Each entry has a `reason` (`bounce`, `complaint`, `unsubscribe` or `manual`) and a human-readable `detail`, such as `Hard bounce (NoEmail)` or `3 soft bounces in 30 days (MailboxFull)`. The first reason recorded for an address is kept: adding an address manually never overwrites a bounce or complaint.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

await spacepost.suppressions.create({ email: "do-not-mail@example.com" });

const { data } = await spacepost.suppressions.list({ limit: 100 });
for (const s of data?.data ?? []) console.log(s.email, s.reason);

await spacepost.suppressions.remove("do-not-mail@example.com"); // by email or id
```
  
  **cURL**

    ```bash
    # list
    curl https://api.spacepost.dev/suppressions?limit=100 -H "Authorization: Bearer $SPACEPOST_API_KEY"

    # add
    curl -X POST https://api.spacepost.dev/suppressions \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{ "email": "do-not-mail@example.com" }'

    # remove, by email or id
    curl -X DELETE https://api.spacepost.dev/suppressions/do-not-mail@example.com -H "Authorization: Bearer $SPACEPOST_API_KEY"
    ```
  

```json title="Suppression"
{
  "object": "suppression",
  "id": "0192e1c4-0000-7000-8000-0000000000d1",
  "email": "nobody@example.com",
  "reason": "bounce",
  "detail": "Hard bounce (NoEmail)",
  "created_at": "2026-10-23T14:02:12.000Z"
}
```

> Note:
Removing an address from the suppression list lets you email it again. Only do it when you are sure the problem is fixed (a typo you corrected, a mailbox that was full), because repeated bounces hurt your reputation and count toward [automatic pausing](/deliverability/auto-pausing/).

## Unreachable recipient domains

If a recipient's domain does not accept mail at all (no MX or A records), SpacePost skips that recipient instead of attempting delivery, and raises `email.suppressed`. This protects your bounce rate. See [Account verification and sending limits](/account/verification-and-limits/#recipient-domains-that-cannot-receive-mail).

## Using test addresses

`bounced@test.spacepost.dev`, `complained@test.spacepost.dev` and (after three sends) `softbounced@test.spacepost.dev` create real suppression entries and count toward your rates. Remove them after testing. See [Testing](/sending/testing/).

---

# Account sandbox

URL: https://docs.spacepost.dev/deliverability/sandbox/

To protect everyone's reputation, every new team starts in a sandbox:

| | Sandbox | After the sandbox |
|---|---|---|
| Period | The first **7 days** after your team is created | Afterwards |
| Daily limit | **100 emails per day** (each recipient counts) | Your [trust level](/account/verification-and-limits/#trust-levels) and plan |
| Sender domains | Verified domains, or the [test sender](/sending/testing/) | Same |
| Applies to | All plans, including paid | n/a |

The day is a UTC calendar day. When you reach the limit, the API returns:

```json
{
  "statusCode": 429,
  "name": "daily_quota_exceeded",
  "message": "New accounts can send 100 emails per day during their first 7 days. Contact support to lift this early."
}
```

The same limit applies over [SMTP](/tools/smtp/) (reply `452`) and to [broadcasts](/audiences/broadcasts/), where the broadcast ends `failed` once the limit is hit.

## Making the most of it

- Use the [test addresses](/sending/testing/) to exercise your integration; they count toward the limit like any email.
- Use the first week to verify your domain, set up webhooks and send real traffic to your engaged users.
- Ramp volume gradually anyway. See [Warming up](/deliverability/warming-up/).

## Lifting the sandbox early

Upgrade to a paid plan, or email [support@spacepost.dev](mailto:support@spacepost.dev) with your use case. See [Account verification and sending limits](/account/verification-and-limits/) for the full picture including trust levels.

The Free plan monthly allowance (3,000 emails) is separate and still applies in the sandbox.

---

# Automatic pausing

URL: https://docs.spacepost.dev/deliverability/auto-pausing/

A burst of bounces or spam complaints damages your reputation and can get an entire sending account throttled by mailbox providers. SpacePost watches your recent mail and **pauses your team** before that happens, well below the thresholds at which Amazon SES starts a review (10% bounce, 0.5% complaint).

## Thresholds

Measured over your **last 1,000 sent emails**, and only once you have sent at least **100**:

| Condition | Pause when |
|---|---|
| Bounces | more than **5%** of those emails bounced **and** at least **10** bounces |
| Complaints | more than **0.2%** drew a complaint **and** at least **3** complaints |

The check runs every time a bounce or complaint is recorded.

## What a pause does

- `POST /emails` and `POST /emails/batch` return `403 sending_paused` with the reason, for example: "Sending is paused for this team: Bounce rate 7.2% over your last 500 emails."
- Emails already queued fail with `email.failed` instead of being sent.
- SMTP sessions are rejected with a permanent error.
- Reading data (emails, domains, webhooks) and the dashboard keep working.

## Recovering

1. Open the dashboard banner or the email log to see why: look at which recipients bounced or complained.
2. Fix the cause: clean the list, remove purchased addresses, stop mailing disengaged users, fix a broken signup form accepting typos.
3. Email [support@spacepost.dev](mailto:support@spacepost.dev) with what happened and what you changed. A person reviews the account and resumes sending.

> Note:
Healthy senders see under 2% bounces and under 0.1% complaints. Verify addresses at signup, use [double opt-in](/deliverability/best-practices/) and act on [`email.bounced`](/webhooks/event-types/) webhooks.

## Tenants (platform mode)

If you send for your own customers with [tenants](/platform/tenants/), each tenant has its own guard with the same thresholds, measured over **that tenant's** last 1,000 emails. A tenant that crosses them is paused on its own: its sends return `403 sending_paused` while your team and your other tenants keep sending. Tenant mail is not counted in your team's own check.

You can pause and resume tenants yourself. To resume a tenant that was paused for its bounce or complaint rate, your team needs to be `trusted`; otherwise `POST /tenants/{ref}/unpause` returns `403 invalid_access` and you should contact support after fixing the cause.

Content filtering and other safety checks are described in [Account verification and sending limits](/account/verification-and-limits/).

---

# Account verification and sending limits

URL: https://docs.spacepost.dev/account/verification-and-limits/

SpacePost shares sending infrastructure and reputation between customers, so we verify who is sending and limit how fast new accounts can grow. The checks are light for legitimate senders. This page lists all of them.

## Sign-up

- **Email verification is required.** You must confirm your email address before you can create API keys or send.
- **You accept the Acceptable Use Policy** (AUP) when you sign up. It prohibits spam, phishing, malware, purchased lists and deceptive content.
- **Disposable email addresses are refused** at sign-up.

## Sending profile

Before you can add your first domain, your team completes a short **sending profile**:

| Field | What we ask |
|---|---|
| Company | Legal or trading name |
| Website | Where we can see who you are |
| Use case | For example transactional, marketing, or both |
| Description | What you send and to whom |
| Expected volume | Emails per month, roughly |
| Opt-in method | For marketing mail: how your recipients agreed to hear from you |

This is not a hurdle, it is how we tell a SaaS sending receipts from a bulk mailer. Be specific and honest: an accurate profile speeds up any later review.

## Domain checks

When you add a domain:

- **Free mail and disposable domains cannot be added** (`gmail.com`, `outlook.com`, `yahoo.com` and similar). Send from a domain you own.
- **Domains registered less than 7 days ago are refused.** Brand-new domains are heavily used for abuse. Come back once the domain is a week old.
- The usual [DNS verification](/domains/adding-and-verifying/) applies.

## Trust levels

Every team has a trust level that sets its daily sending cap. It sits on top of your plan's monthly quota.

| Level | How you get it | Daily cap |
|---|---|---|
| **New** | Every new team | **100 emails per day** for the first 7 days (the [sandbox](/deliverability/sandbox/)) |
| **Verified** | Automatic after 7 days when you have a verified domain, low bounce and complaint rates and no open abuse flags. Immediate when you are on a **paid plan**. | **max(1,000, 2x your best day of the last 14 days)**, up to **50,000** per day |
| **Trusted** | Manual review by the SpacePost team | Plan limits only, no daily cap |

The verified cap grows with you: send 3,000 emails on your best day and tomorrow's cap is 6,000. If you need to go faster, for example for a planned launch, contact [support@spacepost.dev](mailto:support@spacepost.dev) and ask for a review for **Trusted**.

When you hit your daily cap the API returns `429 daily_quota_exceeded`; the monthly plan quota returns `429 monthly_quota_exceeded`. See [Errors](/api/errors/).

## Content filtering

Every email is checked before it is sent:

- **Executable attachments are blocked** (for example `.exe`, `.scr`, `.bat`, `.js` and other file types that run code).
- **Phishing and spam indicators are scored** (deceptive links, credential harvesting wording, known bad patterns). Content over the threshold is blocked.

A blocked send returns **HTTP 451** with the error name `security_error`:

```json
{
  "statusCode": 451,
  "name": "security_error",
  "message": "The email was blocked by content filtering."
}
```

Do not retry a `security_error` without changing the content. If you believe a legitimate email was blocked, contact support with the request details.

## Automatic pausing

Teams with unhealthy bounce or complaint rates are paused automatically:

- bounce rate **above 5%** (with at least 10 bounces), or
- complaint rate **above 0.2%** (with at least 3 complaints),

measured over your last 1,000 emails. While paused, sends return `403 sending_paused`. See [Automatic pausing](/deliverability/auto-pausing/) for recovery.

## Recipient domains that cannot receive mail

Before sending, SpacePost checks that each recipient's domain can receive email. Recipients whose domain does not accept mail (no mail server) are **skipped**, and an `email.suppressed` event is recorded. This keeps typos like `user@gmial.con` from inflating your bounce rate. Other recipients on the same email are still delivered.

## Related

- [Account sandbox](/deliverability/sandbox/)
- [Security and API keys](/account/security/)
- [Plans and quotas](/account/plans-and-quotas/)
- [Deliverability best practices](/deliverability/best-practices/)

---

# Plans and quotas

URL: https://docs.spacepost.dev/account/plans-and-quotas/

| | Free | Pro | Scale | Enterprise |
|---|---|---|---|---|
| Price (EUR, excl. VAT) | €0 | **€9** / month | **€35** / month | Custom |
| Included emails per month | 3,000 | 50,000 | 200,000 | Custom |
| Overage per 1,000 emails (EUR, excl. VAT) | Not available (hard stop) | **€0.25** | **€0.20** | Custom |
| Domains | 3 | 10 | 1,000 | Custom |
| Log retention | 30 days | 30 days | 60 days | Custom |
| API rate limit | 10 requests/s | 10 requests/s | 25 requests/s | Custom |
| Dedicated IP | No | No | No | Yes (passed through at AWS's SES price, currently USD 24.95 per IP per month) |

Prices are in euros (EUR) and exclude VAT; see [VAT](#vat) for how it is added.

New accounts have an additional [daily limit](/deliverability/sandbox/) of 100 emails for the first 7 days. After that, every plan, including Free, has a [trust-level daily cap](/account/verification-and-limits/#trust-levels): at the Verified level it is the larger of 1,000 and twice your best day in the last 14 days, up to 50,000 per day.

## What counts as an email

**Every recipient counts as one email.** The count is taken when the API accepts your request:

| You send | Counts as |
|---|---|
| 1 email, 1 `to` | 1 |
| 1 email, 1 `to` + 2 `cc` + 1 `bcc` | 4 |
| A batch of 100 emails with 1 recipient each | 100 |
| A broadcast to an audience of 5,000 subscribed contacts | 5,000 |
| An email sent over SMTP | One per envelope recipient |
| A send to `delivered@test.spacepost.dev` | 1 |
| A scheduled email | Counted when scheduled; canceling does not refund |

The month is a UTC calendar month. Quota is checked in one transaction, so a request that would exceed your limit is rejected entirely and uses nothing. Reading data and managing domains, keys and webhooks does not count.

## Limits when you reach your quota

- **Free:** at 3,000 emails the API returns `429 monthly_quota_exceeded`. Upgrade or wait for the new month.
- **Pro and Scale:** sending continues. Emails above the included amount are billed as **overage**, per 1,000, rounded up to the cent, together with the next month's fee. Your usage and the estimated next charge are visible live in the dashboard.

## Retention

Email logs, including bodies, events and the details used by `GET /emails/{id}`, are deleted after the retention period. Webhook delivery logs are kept for 30 days; idempotency keys for 24 hours. Suppressions and contacts are kept until you delete them.

## Billing

Paid plans run per **UTC calendar month**, the same month as your quota. Team owners and admins manage billing from **Usage & Billing** in the dashboard. Prices and invoices are in euros (EUR); prices exclude VAT, which is added on top where it applies (see [VAT](#vat)).

- **Billing details first:** before your first checkout you enter the name, address and country to invoice, plus a VAT ID if you buy as a business. The checkout shows the price, the VAT and the total before you pay.
- **Upgrading from Free:** pay by card at checkout. You pay for the rest of the current month only (for example €4.50 plus any VAT for Pro on April 16); on the 1st you pay the full price. The plan applies as soon as the payment goes through. The card is saved for renewals.
- **Renewal:** on the 1st of each month we charge the saved card for the new month plus the previous month's overage.
- **Pro to Scale:** takes effect immediately; we charge the price difference for the rest of the month.
- **Downgrade or cancel:** takes effect on the 1st of the next month. Until then you keep your plan and can undo the change.
- **Card:** replace it any time with **Update card**.
- **Invoices and receipts:** every payment gets a tax invoice in EUR (downloadable from the payment history) and a card receipt. A VAT ID you enter in your billing details appears on the invoice.

## VAT

Prices exclude VAT. What is added depends on the country and VAT ID in your billing details:

| Customer | VAT added |
|---|---|
| In Slovenia (business or consumer) | 22 % Slovenian VAT |
| Consumer in another EU country | The VAT rate of your country |
| Business in another EU country with a valid VAT ID | None: reverse charge, you account for VAT yourself |
| Outside the EU | None |

We check EU VAT IDs in the EU's VIES system before applying the reverse charge. If an ID is not confirmed, VAT is charged as for a consumer in your country.

> Note:
Owners get an email with a link to pay. We retry the card 2 and 4 days after the first failure (on the 3rd and 5th of the month for a renewal on the 1st). If the amount is still unpaid 7 days after the first failure, the team moves to the Free plan: all data is kept, Free limits apply, and you can upgrade again at any time.

> Note:
Resend's Pro plan is USD 20 for 50,000 emails with USD 0.90 per extra 1,000 (Resend's prices in USD as of 23 October 2026, not converted). SpacePost Pro is €9 excl. VAT for the same volume. See [Migrating from Resend](/getting-started/migrating-from-resend/).

---

# Security and API keys

URL: https://docs.spacepost.dev/account/security/

## Key types

| Permission | Can do | Use for |
|---|---|---|
| `full_access` | Every endpoint | Your own tooling, CLI, MCP server, admin scripts |
| `sending_access` | Only `POST /emails` and `POST /emails/batch` | Application servers that just send mail |

Calling any other endpoint with a `sending_access` key returns `401 restricted_api_key` ("This API key is restricted to only send emails").

### Domain-restricted keys

A `sending_access` key can additionally be bound to **one domain** with `domain_id`. It can then only send from addresses on that domain; any other `from` returns `401 restricted_api_key`. Use it to give each product or client its own key.

  **Node.js**

    ```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

// A key that can only send, and only from one domain.
const { data: key, error } = await spacepost.apiKeys.create({
  name: "worker-prod",
  permission: "sending_access",
  domainId: "0192e1c4-0000-7000-8000-000000000001",
});
if (error) throw new Error(error.message);
console.log(key.token); // sp_live_..., shown only once

const { data: keys } = await spacepost.apiKeys.list();
console.log(keys?.data.map((k) => `${k.name} ${k.prefix}... ${k.permission}`));

await spacepost.apiKeys.remove(key.id);
```
  
  **cURL**

    ```bash
    curl -X POST https://api.spacepost.dev/api-keys \
      -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
      -d '{ "name": "worker-prod", "permission": "sending_access", "domain_id": "0192e1c4-0000-7000-8000-000000000001" }'
```
```json title="Response (the token is shown only once)"
{ "id": "0192e1c4-0000-7000-8000-0000000000e1", "token": "sp_live_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56" }
```
  

`name` is 1 to 50 characters. `domain_id` is only allowed with `sending_access`.

## How keys are stored

- Keys look like `sp_live_` followed by 32 random base62 characters.
- SpacePost stores only a **SHA-256 hash**. The full key is shown once, at creation. If you lose it, create a new key.
- The dashboard and `GET /api-keys` show the **prefix** (`sp_live_` plus 4 characters), the permission, the domain and `last_used_at`.
- Deleting a key (`DELETE /api-keys/{id}`) revokes it immediately.

## Good habits

- **Never put keys in client-side code**, mobile apps or public repositories. The API allows cross-origin requests only so API playgrounds work; send email from your server.
- Use one key per service and environment, named clearly (`worker-prod`, `ci-staging`).
- Prefer `sending_access`, restricted to a domain.
- **Rotate** by creating a new key, deploying it, checking `last_used_at` of the old one, then deleting the old one.
- Keep keys in a secret manager or environment variables, not in code.
- Revoke immediately if a key leaks. If it was committed to GitHub, assume it is compromised.
- SMTP uses the same key as the password. See [SMTP relay](/tools/smtp/).

> Note:
Each webhook has its own `signing_secret`. See [Verifying signatures](/webhooks/verifying/).

## Transport

All traffic uses TLS. The API is served at `https://api.spacepost.dev`, and the SMTP relay at `smtp.spacepost.dev:25976` requires STARTTLS before authentication (implicit TLS on port 465 is not offered yet).

Other protections: failed SMTP authentication attempts are throttled per IP; webhook endpoints and attachment URLs must resolve to public addresses (private networks are refused); the unsubscribe links are signed per contact.

## Where your data is stored

SpacePost is operated by Studio 404 d.o.o., an EU company in Slovenia, and keeps customer data in the EU:

- **Sending:** Amazon SES in AWS `eu-central-1` (Frankfurt, Germany). Every domain sends from this region.
- **Application and database:** the API, dashboard, workers and Postgres database run on Railway in its EU region (Amsterdam, Netherlands).
- **Isolation:** each team sends through its own SES tenant, so one customer's reputation problems don't affect others.
- **Website and docs** are static pages served by Cloudflare's global network; no customer data is stored there.

Some providers (AWS, Stripe, Railway) are US companies. They are listed with what they process and where on the [sub-processor list](https://spacepost.dev/legal/subprocessors). A GDPR [data processing addendum](https://spacepost.dev/legal/dpa) is part of the Terms of Service, which are governed by Slovenian law.

## Reporting a vulnerability

Email [support@spacepost.dev](mailto:support@spacepost.dev) with details. Please do not test against other customers' data.

---

# API introduction

URL: https://docs.spacepost.dev/api/introduction/

The SpacePost API is a JSON REST API that is compatible with the Resend API. The complete endpoint list is in the [API reference](/api-reference/), generated from the [OpenAPI spec](/tools/openapi/).

## Base URL

```text
https://api.spacepost.dev
```

Paths are at the root (`/emails`, `/domains`, ...). A `/v1` prefix is also accepted: `https://api.spacepost.dev/v1/emails` is the same endpoint. Use whichever your client prefers.

## Authentication

Send your API key as a bearer token on every request:

```bash
curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_YOUR_API_KEY"
```

Keys start with `sp_live_`. `full_access` keys can use every endpoint; `sending_access` keys can only send emails, optionally from one domain. See [Security and API keys](/account/security/).

| Problem | Response |
|---|---|
| No `Authorization` header | `401 missing_api_key` |
| Unknown, revoked or malformed key (including Resend `re_` keys) | `403 invalid_api_key` |
| `sending_access` key on a non-sending endpoint | `401 restricted_api_key` |

## Requests

- Send JSON with `Content-Type: application/json`. Invalid JSON returns `422 validation_error`.
- Fields are `snake_case` (`reply_to`, `scheduled_at`). For convenience `replyTo` and `scheduledAt` are also accepted when sending.
- IDs are UUIDv7 strings; they sort by creation time, which is how [pagination](/api/pagination/) works.
- Timestamps are ISO 8601 in UTC (`2026-10-23T14:02:09.512Z`).
- Unknown fields on a request are ignored.

## Responses

Successful responses are JSON with status `200`. Resources carry an `object` field naming their type (`"email"`, `"domain"`, ...). Lists look like `{ "object": "list", "has_more": false, "data": [] }`.

Errors always have the same shape:

```json
{ "statusCode": 422, "name": "validation_error", "message": "`to`: Invalid email address" }
```

See [Errors](/api/errors/) for every `name`.

## Idempotency

`POST /emails` and `POST /emails/batch` accept an `Idempotency-Key` header (1 to 256 characters, remembered for 24 hours): the same key and body returns the first response instead of sending again. See [Idempotency keys](/sending/idempotency/).

## Rate limits

Per team: 10 requests per second (25 on Scale), returned in `ratelimit-*` headers. See [Rate limits](/api/rate-limits/).

## Versioning

The API follows Resend's current shapes and does not use dated versions. We only make backward-compatible changes to existing endpoints (new optional fields, new fields in responses, new event types and error names), so write clients that ignore unknown fields and handle unknown error names. Anything breaking would ship under a new path prefix with advance notice in the [changelog](/changelog/).

## CORS

The API sends permissive CORS headers so API explorers can call it, but **never call it from a browser with a real key**. Keys belong on servers.

## SDKs and tools

---

# Errors

URL: https://docs.spacepost.dev/api/errors/

Every error response has the same JSON shape, identical to Resend's:

```json
{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`from`: Invalid email address"
}
```

Branch on `name`, which is stable. `message` is for humans and may change. In the Node SDK, errors come back as `{ data: null, error }` with the same three fields; network failures use `name: "application_error"` and `statusCode: null`.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Hello</p>",
});

if (error) {
  switch (error.name) {
    case "rate_limit_exceeded":
      // wait about a second, then retry with the same idempotency key
      break;
    case "daily_quota_exceeded":
    case "monthly_quota_exceeded":
      // alert someone: you hit a limit
      break;
    case "validation_error":
    case "invalid_from_address":
      // a bug in your request: do not retry
      throw new Error(`${error.name}: ${error.message}`);
    default:
      console.error(error.statusCode, error.name, error.message);
  }
} else {
  console.log(data.id);
}
```

## Error table

| Status | `name` | Meaning and fix |
|---|---|---|
| 400 | `invalid_idempotency_key` | The `Idempotency-Key` header is not 1 to 256 characters. |
| 401 | `missing_api_key` | No `Authorization: Bearer sp_live_...` header. |
| 401 | `restricted_api_key` | The key may not do this: a `sending_access` key used on a non-sending endpoint, or a domain-restricted key sending from another domain. |
| 403 | `invalid_api_key` | The key is unknown, revoked, or not a SpacePost key (for example a Resend `re_` key). |
| 403 | `invalid_from_address` | The `from` domain is not a verified domain of your team. |
| 403 | `sending_paused` | Your team is paused, usually after high bounce or complaint rates, or (when you pass `tenant_id` or send from a tenant-owned domain) that [tenant](/platform/tenants/) is paused. See [Automatic pausing](/deliverability/auto-pausing/). |
| 403 | `validation_error` | A request that is valid but not allowed: using `test.spacepost.dev` to mail recipients other than your team or test addresses, or exceeding your plan's domain limit. |
| 403 | `invalid_access` | Dashboard session without access to the requested team, or `POST /tenants/{ref}/unpause` on a tenant that was paused for its bounce or complaint rate by a team that is not `trusted`. Contact support. |
| 404 | `not_found` | The resource does not exist (or belongs to another team), or the endpoint does not exist. |
| 405 | `method_not_allowed` | The HTTP method is not supported on this path. |
| 409 | `concurrent_idempotent_requests` | The same idempotency key is still being processed. Retry shortly. |
| 409 | `invalid_idempotent_request` | The idempotency key was already used with a different request body. |
| 422 | `validation_error` | A field is missing or invalid. The message names it. Also: "Only scheduled emails can be canceled", "Domain already registered", invalid JSON, a `tenant_id` that conflicts with the domain's tenant, a duplicate tenant `external_id`, deleting a tenant that still has domains. |
| 422 | `invalid_parameter` | A query or path parameter is invalid. |
| 429 | `rate_limit_exceeded` | Over your requests-per-second limit. Wait for `retry-after` seconds. |
| 429 | `daily_quota_exceeded` | The daily sending limit was reached (new-account [sandbox](/deliverability/sandbox/), your trust-level cap, or a [tenant's](/platform/tenants/) `daily_limit`). |
| 429 | `monthly_quota_exceeded` | The Free plan's monthly limit was reached. Upgrade or wait. |
| 451 | `security_error` | The email was blocked by [content filtering](/account/verification-and-limits/#content-filtering) (executable attachment, phishing or spam indicators). Change the content; do not retry as is. |
| 500 | `application_error` | Unexpected error from the API. Retry with backoff. |
| 500 | `internal_server_error` | "An unexpected error occurred, please try again later". Retry with backoff; contact support if persistent. |

## Retrying

| Retry? | Errors |
|---|---|
| Yes, after the `retry-after` seconds | `rate_limit_exceeded` |
| Yes, with exponential backoff and the same `Idempotency-Key` | `500`s, network errors, `concurrent_idempotent_requests` |
| No, fix the request | `400`, `401`, `403`, `404`, `422` |
| No, wait for the limit to reset or upgrade | `daily_quota_exceeded`, `monthly_quota_exceeded` |
| No, ask support (or unpause a tenant you paused yourself) | `sending_paused`, `security_error` |

## Webhooks and asynchronous failures

Errors above are returned when you **make a request**. Problems that happen after an email is accepted (bounces, rejections) arrive as [webhook events](/webhooks/event-types/) and in the email's `last_event`.

Over SMTP, the same conditions are returned as SMTP reply codes: quota errors `452`, rate limiting `421`, invalid sender `553`, other rejections `550`, temporary faults `451`.

---

# Rate limits

URL: https://docs.spacepost.dev/api/rate-limits/

The API limits **requests per second per team** (not per key):

| Plan | Requests per second |
|---|---|
| Free | 10 |
| Pro | 10 |
| Scale | 25 |
| Enterprise | Custom |

Resend's limit is 2 requests per second. A [batch](/sending/batch/) of up to 100 emails is **one** request, so you can send thousands of emails per second within the limit.

Limits are applied in one-second windows. Dashboard sessions are not rate limited. Sending quotas ([Plans and quotas](/account/plans-and-quotas/)) are separate from request limits.

## Headers

Every response includes:

| Header | Meaning |
|---|---|
| `ratelimit-limit` | Requests allowed per window (for example `10`). |
| `ratelimit-remaining` | Requests left in the current window. |
| `ratelimit-reset` | Seconds until the window resets (`1`). |
| `retry-after` | Only on `429`: seconds to wait before retrying (`1`). |

```text
HTTP/1.1 429 Too Many Requests
ratelimit-limit: 10
ratelimit-remaining: 0
ratelimit-reset: 1
retry-after: 1

{ "statusCode": 429, "name": "rate_limit_exceeded", "message": "Too many requests. You can only make 10 requests per second." }
```

## Handling 429

  **Node.js**

```ts
import { SpacePost, type SendEmailOptions } from "@spacepost/node";

const spacepost = new SpacePost();

async function sendWithRetry(email: SendEmailOptions, key: string, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    const { data, error } = await spacepost.emails.send(email, { idempotencyKey: key });
    if (!error) return data;
    if (error.name !== "rate_limit_exceeded") throw new Error(`${error.name}: ${error.message}`);
    await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
  }
  throw new Error("rate limited");
}
```
  
  **Python**

```python
import time, requests

def post_with_retry(url, headers, json, attempts=5):
    for _ in range(attempts):
        r = requests.post(url, headers=headers, json=json, timeout=15)
        if r.status_code != 429:
            return r
        time.sleep(float(r.headers.get("retry-after", 1)))
    return r
```
  

Always reuse the same `Idempotency-Key` on retries so a request that actually succeeded is not repeated.

## Tips

- Prefer batches over many single sends.
- Queue sends in a background worker and cap its concurrency to your limit.
- Spread import jobs (for example creating contacts) at a steady pace.

> Note:
Limits are enforced per server instance with a one-second window; occasional bursts at the boundary of two windows are possible. Treat the headers as authoritative.

---

# Pagination

URL: https://docs.spacepost.dev/api/pagination/

List endpoints (`GET /emails`, `/domains`, `/api-keys`, `/webhooks`, `/audiences`, `/audiences/{id}/contacts`, `/broadcasts`, `/suppressions`) share one cursor-based scheme.

| Parameter | Description |
|---|---|
| `limit` | Items per page, 1 to 100. Default **20**. |
| `after` | An item id. Returns the page of items **older** than it (the next page). |
| `before` | An item id. Returns the page of items **newer** than it (the previous page). |

Use only one of `after` and `before`; both together return `422`. Results are **newest first**. Cursors are item ids (UUIDv7, which sort by creation time), so pages stay stable while new items arrive.

```json title="Response"
{
  "object": "list",
  "has_more": true,
  "data": [
    { "object": "email", "id": "0192e1c4-7a3c-7a02-8e10-6c0f9d7a2b31", "...": "..." },
    { "object": "email", "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10", "...": "..." }
  ]
}
```

`has_more` tells you whether another page exists in the direction you were paging.

## Walk every page

  **Node.js**

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

let after: string | undefined;
for (;;) {
  const { data, error } = await spacepost.emails.list({ limit: 100, after });
  if (error) throw new Error(error.message);
  for (const email of data.data) console.log(email.id, email.last_event);
  if (!data.has_more) break;
  after = data.data[data.data.length - 1]!.id;
}
```
  
  **cURL**

```bash
curl "https://api.spacepost.dev/emails?limit=100" -H "Authorization: Bearer $SPACEPOST_API_KEY"
curl "https://api.spacepost.dev/emails?limit=100&after=0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" -H "Authorization: Bearer $SPACEPOST_API_KEY"
```
  
  **Python**

```python
after = None
while True:
    params = {"limit": 100, **({"after": after} if after else {})}
    page = requests.get("https://api.spacepost.dev/emails", headers=h, params=params).json()
    for email in page["data"]:
        print(email["id"], email["last_event"])
    if not page["has_more"]:
        break
    after = page["data"][-1]["id"]
```
  

## Notes

- List responses for emails omit `html` and `text`; fetch one email to get its body.
- List responses for domains omit `records`; fetch one domain to get them.
- A malformed cursor returns `422 validation_error` ("Invalid pagination cursor").

---

# Node.js SDK

URL: https://docs.spacepost.dev/tools/node-sdk/

`@spacepost/node` is a zero-dependency, `fetch`-based client with the same method names and `{ data, error }` return shape as the Resend SDK. It runs on Node 18+, Bun, Deno and edge runtimes.

```bash
npm install @spacepost/node
# or: bun add @spacepost/node | pnpm add @spacepost/node | yarn add @spacepost/node
```

## Setup

```ts
import { SpacePost } from "@spacepost/node";

// Reads SPACEPOST_API_KEY (and SPACEPOST_BASE_URL) from the environment when no key is passed.
const spacepost = new SpacePost();

// Or configure explicitly, for example in tests or against a self-hosted deployment.
const custom = new SpacePost("sp_live_YOUR_API_KEY", { baseUrl: "https://api.spacepost.dev" });

console.log(spacepost.baseUrl, custom.baseUrl);
```

| Constructor | Environment fallback | Default |
|---|---|---|
| `new SpacePost(apiKey)` | `SPACEPOST_API_KEY` | none; throws if missing |
| `{ baseUrl }` | `SPACEPOST_BASE_URL` | `https://api.spacepost.dev` |
| `{ fetch }` | n/a | global `fetch` (inject for tests or proxies) |
| `{ userAgent }` | n/a | `spacepost-node/<version>` |

## Results and errors

Every method returns a promise of `{ data, error }`. Exactly one is non-null. **Methods never throw on API or network errors.**

```ts
const { data, error } = await spacepost.emails.get(id);
if (error) {
  // error.name        "not_found" | "validation_error" | ...
  // error.message     human readable
  // error.statusCode  HTTP status, or null when the request never got a response
  return;
}
console.log(data.last_event);
```

(`webhooks.verify` is the exception: it throws on an invalid signature.)

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Hello</p>",
});

if (error) {
  switch (error.name) {
    case "rate_limit_exceeded":
      // wait about a second, then retry with the same idempotency key
      break;
    case "daily_quota_exceeded":
    case "monthly_quota_exceeded":
      // alert someone: you hit a limit
      break;
    case "validation_error":
    case "invalid_from_address":
      // a bug in your request: do not retry
      throw new Error(`${error.name}: ${error.message}`);
    default:
      console.error(error.statusCode, error.name, error.message);
  }
} else {
  console.log(data.id);
}
```

Request fields can be written in camelCase (`replyTo`, `scheduledAt`, `contentType`, `audienceId`, `tenantId`, `externalId`, `dailyLimit`) or snake_case; the SDK converts. Responses are returned exactly as the API sends them (snake_case).

## Method overview

| Namespace | Methods |
|---|---|
| `emails` | `send`, `get`, `list`, `update`, `cancel` |
| `batch` | `send` |
| `domains` | `create`, `get`, `list`, `verify`, `update`, `remove` |
| `apiKeys` | `create`, `list`, `remove` |
| `webhooks` | `create`, `get`, `list`, `update`, `remove`, `verify` |
| `audiences` | `create`, `get`, `list`, `remove` |
| `contacts` | `create`, `get`, `list`, `update`, `remove` |
| `broadcasts` | `create`, `get`, `list`, `update`, `remove`, `send` |
| `suppressions` | `list`, `create`, `remove` |
| `tenants` | `create`, `get`, `list`, `update`, `remove`, `pause`, `unpause` |

## emails

`send(payload, { idempotencyKey? })`, `get(id)`, `list({ limit, after, before })`, `update({ id, scheduledAt })`, `cancel(id)`.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

// send
const { data: sent } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Hello</p>",
  scheduledAt: "in 1 hour",
});

if (sent) {
  // get: includes html/text and last_event
  const { data: email } = await spacepost.emails.get(sent.id);
  console.log(email?.last_event); // "scheduled"

  // update: reschedule
  await spacepost.emails.update({ id: sent.id, scheduledAt: "in 3 hours" });

  // cancel
  await spacepost.emails.cancel(sent.id);
}

// list: cursor pagination, newest first, bodies omitted
const { data: page } = await spacepost.emails.list({ limit: 10 });
if (page?.has_more) {
  const last = page.data[page.data.length - 1]!;
  const { data: older } = await spacepost.emails.list({ limit: 10, after: last.id });
  console.log(older?.data.length);
}
```

`send` accepts every field of [Send an email](/sending/send-email/), including `tenantId` for [platform mode](/platform/tenants/), plus `react` for React Email (needs the optional peer dependency `@react-email/render`; see [React Email](/sending/react-email/)). Attachment `content` may be a base64 string, a `Buffer` or a `Uint8Array`.

## batch

`batch.send(emails, { idempotencyKey? })` sends up to 100 emails (each may carry its own `tenantId`) and resolves to `{ data: { data: [{ id }] } }`. See [Batch sending](/sending/batch/).

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.batch.send(
  [
    { from: "Acme <hello@acme.com>", to: ["a@example.com"], subject: "Hi Ada", html: "<p>Hi Ada</p>" },
    { from: "Acme <hello@acme.com>", to: ["b@example.com"], subject: "Hi Bob", html: "<p>Hi Bob</p>" },
  ],
  { idempotencyKey: "weekly-digest-2026-w43" },
);

if (error) console.error(error);
else console.log(data.data.map((e) => e.id)); // ids in input order
```

## domains

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

const { data: domain } = await spacepost.domains.create({ name: "acme.com", customReturnPath: "send" });
if (domain) {
  await spacepost.domains.verify(domain.id);
  const { data: fresh } = await spacepost.domains.get(domain.id); // includes records
  console.log(fresh?.status, fresh?.records);

  await spacepost.domains.update({ id: domain.id, openTracking: true, clickTracking: true });
  await spacepost.domains.remove(domain.id);
}

const { data: all } = await spacepost.domains.list(); // no records in lists
console.log(all?.data.map((d) => d.name));
```

`create({ name, region?, customReturnPath?, tenantId? })`, `get(id)` (with `records`), `list()`, `verify(id)`, `update({ id, openTracking?, clickTracking? })`, `remove(id)`. See [Adding and verifying](/domains/adding-and-verifying/).

## apiKeys

`create({ name, permission?, domainId? })` returns `{ id, token }`; the token is shown once.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

// A key that can only send, and only from one domain.
const { data: key, error } = await spacepost.apiKeys.create({
  name: "worker-prod",
  permission: "sending_access",
  domainId: "0192e1c4-0000-7000-8000-000000000001",
});
if (error) throw new Error(error.message);
console.log(key.token); // sp_live_..., shown only once

const { data: keys } = await spacepost.apiKeys.list();
console.log(keys?.data.map((k) => `${k.name} ${k.prefix}... ${k.permission}`));

await spacepost.apiKeys.remove(key.id);
```

## webhooks

`create`, `get`, `list`, `update`, `remove` manage endpoints ([Webhooks](/webhooks/overview/)).

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: webhook, error } = await spacepost.webhooks.create({
  endpoint: "https://acme.com/webhooks/spacepost",
  events: ["email.delivered", "email.bounced", "email.complained"],
});
if (error) throw new Error(`${error.name}: ${error.message}`);

// Store this secret: you need it to verify signatures. It starts with "whsec_".
console.log(webhook.id, webhook.signing_secret);
```

`verify({ payload, headers, secret })` checks a delivery's signature and returns the parsed event, or **throws**. Pass the raw body; `headers` can be a `Headers` object or a plain object.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

/** Works as a Bun, Deno, Cloudflare Workers or Next.js route handler. */
export async function POST(request: Request): Promise<Response> {
  const payload = await request.text(); // the RAW body: do not parse it first

  try {
    const event = await spacepost.webhooks.verify({
      payload,
      headers: request.headers,
      secret: process.env.SPACEPOST_WEBHOOK_SECRET!,
    });

    switch (event.type) {
      case "email.bounced":
      case "email.complained":
        console.warn("Stop mailing", event.data.to);
        break;
      case "email.delivered":
        console.log("Delivered", event.data.email_id);
        break;
    }
    return new Response("ok");
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
}
```

Webhook events are typed. `verify` returns a `WebhookPayload`, a union discriminated by `type`, so narrowing on `event.type` gives you `data.bounce`, `data.click`, `data.open`, `data.failed` or `data.suppressed`. Every event also has `data.tenant_id` when the email was sent for a tenant. See [Event types](/webhooks/event-types/).

## tenants

Platform mode: one tenant per customer you send for, with isolated reputation, a pause switch and an optional daily cap. See the [Platform mode guide](/platform/tenants/).

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

// One tenant per customer. `externalId` is your own customer id and works anywhere a tenant id does.
const { data: tenant, error } = await spacepost.tenants.create({
  name: "Acme Inc",
  externalId: "cust_123",
  dailyLimit: 500, // optional cap, in recipients per UTC day
});
if (error) throw new Error(`${error.name}: ${error.message}`);
console.log(tenant.id, tenant.status); // "active"

// Optional: give the tenant its own sending domain. Mail from it is attributed to the tenant automatically.
const { data: domain } = await spacepost.domains.create({ name: "mail.acme-inc.com", tenantId: "cust_123" });
console.log(domain?.tenant_id === tenant.id); // true
```

`create({ name, externalId?, dailyLimit? })`, `get(idOrExternalId)`, `list({ limit, after, before })`, `update({ id, name?, externalId?, dailyLimit? })` (`dailyLimit: null` removes the cap), `remove(idOrExternalId)` (422 while the tenant has domains), `pause({ id, reason? })` (or `pause(id)`) and `unpause(idOrExternalId)` (403 for reputation pauses unless your team is trusted). Anywhere an id is expected you can pass your `external_id`.

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: page } = await spacepost.tenants.list({ limit: 20 });
for (const t of page?.data ?? []) console.log(t.name, t.external_id, t.status, t.paused_reason);

await spacepost.tenants.get("cust_123"); // by external_id or our id
await spacepost.tenants.update({ id: "cust_123", dailyLimit: 1000 }); // dailyLimit: null removes the cap

await spacepost.tenants.pause({ id: "cust_123", reason: "Investigating spam reports" });

const { error } = await spacepost.tenants.unpause("cust_123");
if (error?.statusCode === 403) console.warn("Paused by the reputation guard; contact support to review it.");

// Domains first, then the tenant (422 while it still has domains).
const { data: domains } = await spacepost.domains.list({ limit: 100 });
for (const d of domains?.data ?? []) if (d.tenant_id) console.log(d.name, "belongs to", d.tenant_id);
await spacepost.tenants.remove("cust_123");
```

## audiences and contacts

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data: audience, error } = await spacepost.audiences.create({ name: "Newsletter" });
if (error) throw new Error(error.message);

// Create
await spacepost.contacts.create({
  audienceId: audience.id,
  email: "ada@example.com",
  firstName: "Ada",
  lastName: "Lovelace",
});

// Read by email (or by id)
const { data: contact } = await spacepost.contacts.get({ audienceId: audience.id, email: "ada@example.com" });
console.log(contact?.unsubscribed);

// Update
await spacepost.contacts.update({ audienceId: audience.id, email: "ada@example.com", firstName: "Augusta" });

// List, newest first
const { data: page } = await spacepost.contacts.list({ audienceId: audience.id, limit: 50 });
console.log(page?.data.length, page?.has_more);

// Unsubscribe manually, then delete
await spacepost.contacts.update({ audienceId: audience.id, email: "ada@example.com", unsubscribed: true });
await spacepost.contacts.remove({ audienceId: audience.id, email: "ada@example.com" });
```

Contacts are addressed with `audienceId` plus either `id` or `email`.

## broadcasts

`create`, `get`, `list`, `update(id, payload)` (or `update({ id, ... })`), `remove`, `send(id, { scheduledAt? })`. See [Broadcasts](/audiences/broadcasts/).

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
const audienceId = "0192e1c4-0000-7000-8000-0000000000a1";

// 1. Create a draft
const { data: draft, error } = await spacepost.broadcasts.create({
  audienceId,
  name: "October newsletter",
  from: "Acme <news@acme.com>",
  replyTo: "support@acme.com",
  subject: "What's new at Acme, {{{FIRST_NAME|friend}}}",
  previewText: "Three things we shipped this month",
  html: `
    <h1>Hi {{{FIRST_NAME|there}}},</h1>
    <p>Here is what is new.</p>
    <p><a href="{{{SPACEPOST_UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>
  `,
});
if (error) throw new Error(error.message);

// 2. Send it now, or schedule it
const { error: sendError } = await spacepost.broadcasts.send(draft.id, { scheduledAt: "in 1 hour" });
if (sendError) throw new Error(sendError.message);

// 3. Check progress
const { data: broadcast } = await spacepost.broadcasts.get(draft.id);
console.log(broadcast?.status); // "queued" | "sending" | "sent" | "failed"
```

## suppressions

```ts
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

await spacepost.suppressions.create({ email: "do-not-mail@example.com" });

const { data } = await spacepost.suppressions.list({ limit: 100 });
for (const s of data?.data ?? []) console.log(s.email, s.reason);

await spacepost.suppressions.remove("do-not-mail@example.com"); // by email or id
```

## Idempotency

The second argument of `emails.send` and `batch.send` takes `{ idempotencyKey }`. See [Idempotency keys](/sending/idempotency/).

## Using the Resend SDK instead

You do not need `@spacepost/node`: the official `resend` package works unchanged against SpacePost. Set `RESEND_BASE_URL=https://api.spacepost.dev` or pass `new Resend(key, { baseUrl: "https://api.spacepost.dev" })`. See [Migrating from Resend](/getting-started/migrating-from-resend/).

SpacePost extras such as `tenant_id` are not part of the Resend SDK's methods, which drop unknown fields. Use `@spacepost/node`, `resend.post("/emails", { ..., tenant_id })` or tenant-owned domains; see [Platform mode](/platform/tenants/#send-for-a-tenant).

## TypeScript

All request and response types are exported: `import type { SendEmailOptions, Email, Domain, Tenant, WebhookPayload } from "@spacepost/node"`. Emails and domains include `tenant_id: string | null`.

---

# CLI

URL: https://docs.spacepost.dev/tools/cli/

```bash
npm install -g spacepost        # or run without installing: npx spacepost <command>, bunx spacepost <command>
spacepost login
spacepost send --from "Acme <hi@acme.com>" --to you@example.com --subject Hello --text "It works"
```

Run `spacepost --help` for all commands and `spacepost <command> --help` for one command's options.

## Authentication

`spacepost login` asks for your API key, checks it against the API and stores it in `~/.config/spacepost/config.json` (mode `0600`, honors `XDG_CONFIG_HOME`). Piped input works too: `echo $KEY | spacepost login`. In CI or scripts set the environment variable instead:

```bash
export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"
spacepost whoami
```

The key comes from `--api-key`, then `SPACEPOST_API_KEY`, then the stored login. The API base URL comes from `--base-url`, then `SPACEPOST_BASE_URL`, then the stored login, then `https://api.spacepost.dev`.

## Commands

| Command | What it does |
|---|---|
| `login`, `logout`, `whoami` | Manage credentials. `whoami` shows the masked key, base URL and domain count |
| `send` | Send an email |
| `emails list`, `emails get <id>`, `emails cancel <id>` | Inspect emails, cancel scheduled ones |
| `domains add <name>`, `list`, `get <id\|name>`, `verify <id\|name>`, `doctor <id\|name>`, `rm <id\|name>` | Manage domains by id or name |
| `keys create`, `keys list`, `keys rm <id>` | API keys |
| `webhooks list`, `webhooks create`, `webhooks rm <id>` | Webhook endpoints |
| `tenants list`, `create`, `get <ref>`, `pause <ref>`, `unpause <ref>`, `rm <ref>` | [Platform mode](/platform/tenants/) tenants |
| `open` | Print (and open) the dashboard URL |

Global flags: `--api-key`, `--base-url`, `--json`, `-y/--yes` (skip confirmations), `-h/--help`, `-v/--version`. Colors honor `NO_COLOR`.

## Send

```bash
spacepost send \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "Hello from the CLI" \
  --html "<p>It works.</p>"

spacepost send --from hello@acme.com --to a@example.com --to b@example.com --subject "Newsletter" --html-file ./email.html
spacepost send --from hello@acme.com --to user@example.com --subject "Reminder" --text "Call at 3" --schedule "in 1 hour"
echo "body from stdin" | spacepost send --from hello@acme.com --to user@example.com --subject Hi --text -
```

| Flag | Description |
|---|---|
| `--from` | Sender on a verified domain (required) |
| `--to` | Recipient (required; **repeat** the flag for several) |
| `--subject` | Subject (required) |
| `--text`, `--html`, `--html-file` | Body: plain text (`-` reads stdin), inline HTML, or an HTML file. At least one is required; `--html` and `--html-file` cannot be combined |
| `--cc`, `--bcc`, `--reply-to` | Repeatable |
| `--tag name=value` | Repeatable tag |
| `--schedule "in 1 hour"` | ISO 8601 time or natural language |
| `--attach <file>` | Repeatable file attachment |
| `--tenant <id\|external-id>` | Send on behalf of a [tenant](/platform/tenants/) |

On success it prints `✓ Queued: <id>` (with `--json`, the API response `{ "id": "..." }`).

## Emails

```bash
spacepost emails list [--limit 20] [--after <id>] [--before <id>]
spacepost emails get <id>
spacepost emails cancel <id>      # scheduled emails only
```

## Domains

```bash
spacepost domains add acme.com [--region eu-central-1] [--tenant cust_123]
spacepost domains list [--limit 20]
spacepost domains get acme.com          # id or name, includes DNS records
spacepost domains verify acme.com
spacepost domains rm acme.com [--yes]
```

`domains add` prints the DNS records to create. `--tenant` makes the domain tenant-owned (see [Platform mode](/platform/tenants/)).

### domains doctor

`spacepost domains doctor <id|name>` looks up every expected DNS record (CNAME, TXT, MX) in public DNS, compares it with what SpacePost expects and prints what is missing or wrong, with a fix for each. It detects the domain name appended twice by a DNS provider, several SPF records, a wrong MX priority and Cloudflare proxying.

```
$ spacepost domains doctor acme.com
acme.com  API status: pending

   RECORD  TYPE   HOST                              RESULT
✓  DKIM    CNAME  abc._domainkey.acme.com           matches
✗  SPF     MX     send.acme.com                     not found
✗  SPF     TXT    send.acme.com                     found v=spf1 include:_spf.google.com ~all
!  DMARC   TXT    _dmarc.acme.com                   not found (recommended)

How to fix
  ✗ MX send.acme.com
      Add a MX record: name "send", value "feedback-smtp.eu-central-1.amazonses.com", priority 10.
  ✗ TXT send.acme.com
      Your SPF record lacks the SpacePost include. ...
```

Use `--dns-server 1.1.1.1` to bypass a stale local resolver cache. The exit code is `1` when a required record is missing or wrong, so it works as a CI check.

## API keys and webhooks

```bash
spacepost keys create --name worker-prod --permission sending_access --domain <domain-id>
spacepost keys list
spacepost keys rm <id> [--yes]

spacepost webhooks list
spacepost webhooks create --endpoint https://acme.com/webhooks/spacepost --event email.delivered --event email.bounced
spacepost webhooks rm <id> [--yes]
```

`keys create` prints the token once. `webhooks create` prints the `signing_secret`. `--event` is repeatable (there is no comma-separated form), and `--domain` requires `--permission sending_access`.

## Tenants (platform mode)

```bash
spacepost tenants create --name "Acme Inc" --external-id cust_123 --daily-limit 500
spacepost tenants list [--limit 20]
spacepost tenants get cust_123                 # <ref> is our id or your external id
spacepost tenants pause cust_123 --reason "Investigating spam reports"
spacepost tenants unpause cust_123             # 403 for reputation pauses unless your team is trusted
spacepost tenants rm cust_123 [--yes]          # 422 while the tenant still has domains
```

See [Platform mode (tenants)](/platform/tenants/) for what tenants isolate and how domains and webhooks fit in.

## Scripting

```bash
spacepost emails list --json | jq -r '.data[] | select(.last_event=="bounced") | .to[]'
id=$(spacepost send --from hello@acme.com --to delivered@test.spacepost.dev --subject Test --text hi --json | jq -r .id)
spacepost emails get "$id" --json | jq .last_event
```

Destructive commands (`domains rm`, `keys rm`, `webhooks rm`, `tenants rm`) ask for confirmation; in scripts and with `--json` pass `--yes`.

## Exit codes and errors

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | API or runtime error (also `domains doctor` when a required record is missing) |
| `2` | Usage error: unknown command or flag, missing required option |

Errors go to stderr with a hint where there is one. With `--json` they are printed as JSON on stderr: `{ "error": { "name", "message", "statusCode", "hint" } }`.

## Environment variables

| Variable | Purpose |
|---|---|
| `SPACEPOST_API_KEY` | API key (overrides the stored login) |
| `SPACEPOST_BASE_URL` | Alternate API base URL |
| `SPACEPOST_APP_URL` | Dashboard URL printed by `spacepost open` |
| `XDG_CONFIG_HOME` | Where the login is stored (`$XDG_CONFIG_HOME/spacepost/config.json`) |
| `NO_COLOR` | Disable colors |

---

# MCP server

URL: https://docs.spacepost.dev/tools/mcp/

SpacePost speaks the [Model Context Protocol](https://modelcontextprotocol.io), so AI assistants can send email and manage domains, API keys, webhooks, audiences, contacts, broadcasts, suppressions and tenants on your behalf.

**Every endpoint in the [API reference](/api-reference/) is an MCP tool.** The tools are generated from the same OpenAPI document as the reference, so when the API gains a feature, the MCP server offers it automatically: there is no separate list to maintain or wait for.

You can connect in two ways:

- **Hosted** (recommended): `https://api.spacepost.dev/mcp`, Streamable HTTP, authenticated with your API key. Nothing to install.
- **Local**: `npx -y @spacepost/mcp`, a stdio server that calls the API from your machine. The tool definitions ship inside the package, so it starts offline.

> Note:
The assistant acts with the permissions of the API key you give it, exactly as if it called the REST API: same permission checks, rate limits, quotas and idempotency. Use a dedicated key. A `sending_access` key can only use `send_email` and `send_batch_emails`: the hosted server lists just those two for such a key, and any other tool answers `restricted_api_key`. Add `--read-only` (local) or `?read_only=true` (hosted) to expose only the tools that read.

## Connect to the hosted server

Send your API key as a bearer token: `Authorization: Bearer sp_live_...`.

  **Claude Code**

```bash
claude mcp add --transport http spacepost https://api.spacepost.dev/mcp \
  --header "Authorization: Bearer sp_live_YOUR_API_KEY"
```
    Use `claude mcp list` to confirm.
  
  **Claude Desktop**

    Claude Desktop starts local (stdio) servers from `claude_desktop_config.json`, so bridge the hosted endpoint with `mcp-remote`
    (Settings, Developer, Edit Config):

```json
{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.spacepost.dev/mcp",
        "--header", "Authorization:${SPACEPOST_AUTH}"
      ],
      "env": { "SPACEPOST_AUTH": "Bearer sp_live_YOUR_API_KEY" }
    }
  }
}
```
    Restart Claude Desktop. Or use the [local server](#run-the-server-locally) instead.
  
  **Cursor**

    Add to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "spacepost": {
      "url": "https://api.spacepost.dev/mcp",
      "headers": { "Authorization": "Bearer sp_live_YOUR_API_KEY" }
    }
  }
}
```
  
  **VS Code**

    Add to `.vscode/mcp.json`:

```json
{
  "inputs": [
    { "id": "spacepost-key", "type": "promptString", "description": "SpacePost API key", "password": true }
  ],
  "servers": {
    "spacepost": {
      "type": "http",
      "url": "https://api.spacepost.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:spacepost-key}" }
    }
  }
}
```
    VS Code asks for the key the first time and keeps it out of the file.
  

Narrow the tool list with query parameters on the URL, for example `https://api.spacepost.dev/mcp?read_only=true&toolsets=emails,domains`.

The hosted server is stateless: each request is independent, so `GET` and `DELETE` on `/mcp` answer `405` and there is no session to resume.

## Run the server locally

| Variable | Required | Description |
|---|---|---|
| `SPACEPOST_API_KEY` | Yes | Your API key |
| `SPACEPOST_BASE_URL` | No | Alternate API URL, default `https://api.spacepost.dev` |
| `SPACEPOST_DEFAULT_FROM` | No | Sender used when the assistant calls `send_email` without `from`, for example `Acme <hello@acme.com>` |
| `SPACEPOST_READ_ONLY` | No | `true` is the same as `--read-only` |
| `SPACEPOST_TOOLSETS` | No | Same as `--toolsets`, for example `emails,domains` |
| `SPACEPOST_PERMISSION` | No | Same as `--permission`; set `sending_access` when the key is send-only |

  **Claude Code**

```bash
claude mcp add spacepost -e SPACEPOST_API_KEY=sp_live_YOUR_API_KEY -- npx -y @spacepost/mcp
```
    Add `-e SPACEPOST_DEFAULT_FROM="Acme <hello@acme.com>"` to set a default sender, or flags after the package name, such as `npx -y @spacepost/mcp --read-only`.
  
  **Claude Desktop**

```json
{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": ["-y", "@spacepost/mcp"],
      "env": {
        "SPACEPOST_API_KEY": "sp_live_YOUR_API_KEY",
        "SPACEPOST_DEFAULT_FROM": "Acme <hello@acme.com>"
      }
    }
  }
}
```
  
  **Cursor**

```json
{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": ["-y", "@spacepost/mcp", "--toolsets", "emails,domains"],
      "env": { "SPACEPOST_API_KEY": "sp_live_YOUR_API_KEY" }
    }
  }
}
```
  
  **VS Code**

```json
{
  "inputs": [
    { "id": "spacepost-key", "type": "promptString", "description": "SpacePost API key", "password": true }
  ],
  "servers": {
    "spacepost": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@spacepost/mcp"],
      "env": { "SPACEPOST_API_KEY": "${input:spacepost-key}" }
    }
  }
}
```
  

`npx -y @spacepost/mcp --help` lists the options, and `--list-tools` prints the tools a configuration exposes.

## Options

| Local flag | Hosted query | Effect |
|---|---|---|
| `--read-only` | `read_only=true` | Only tools for `GET` endpoints (`list_*`, `get_*`, `get_broadcast_readiness`) |
| `--permission sending_access` | automatic, from your key | Only the tools a `sending_access` key can use |
| `--toolsets emails,domains` | `toolsets=emails,domains` | Only tools of these API areas: `emails`, `domains`, `apikeys`, `webhooks`, `audiences`, `contacts`, `broadcasts`, `suppressions`, `tenants` (the reference's sections; case, spaces and dashes are ignored, so `api-keys` works too) |

Both can be combined.

## How tools map to the API

- **One tool per endpoint**, named after the endpoint's `operationId` in snake_case: `sendEmail` becomes `send_email`, `getBroadcastReadiness` becomes `get_broadcast_readiness`, `pauseTenant` becomes `pause_tenant`. The [API reference](/api-reference/) documents every field.
- **Arguments** are one flat object: path parameters (in snake_case, e.g. `id`, `audience_id`, `ref`), query parameters (`limit`, `after`, `before`) and the fields of the JSON body (`from`, `to`, `subject`, ...). If a body field has the same name as a parameter, it is called `body_<field>`. A body that is not an object, such as the array for `send_batch_emails`, is passed as `body`.
- **`idempotency_key`** on `send_email` and `send_batch_emails` sets the `Idempotency-Key` header, so retries never send twice.
- **Results** are the API's JSON response, also as structured content. Errors come back with `isError: true` and the same `{ "statusCode", "name", "message" }` body as the REST API, plus a hint on what to do next.
- **Annotations** tell the client what a tool does: read tools are `readOnlyHint`, deletes, `cancel_email` and `pause_tenant` are `destructiveHint`, and the tools that send email (`send_email`, `send_batch_emails`, `send_broadcast`) are `openWorldHint`. Clients use them to decide when to ask you before running a tool.

## Example prompts

- "Send a test email from onboarding@test.spacepost.dev to delivered@test.spacepost.dev saying hello."
- "Add the domain acme.com and tell me which DNS records to create."
- "Did the email I sent to ada@example.com yesterday get delivered?"
- "Cancel the scheduled email to the beta list."
- "Create a webhook to https://acme.com/hooks for bounces and complaints."
- "Draft a broadcast to my Newsletter audience, check it for deliverability problems, but don't send it yet."
- "Which of my tenants are paused, and why?"

> Note:
Give your coding agent the docs too: [`/llms.txt`](/llms.txt) is an index and [`/llms-full.txt`](/llms-full.txt) has the key pages in one file.

---

# SMTP relay

URL: https://docs.spacepost.dev/tools/smtp/

The SMTP relay lets software that only speaks SMTP (CMSs, auth providers, frameworks, legacy apps) send through SpacePost. Messages go through the same pipeline as the API: domain checks, suppression list, quotas, tracking, webhooks.

| Setting | Value |
|---|---|
| Host | `smtp.spacepost.dev` |
| Port | `25976` |
| Security | STARTTLS, required before authenticating |
| Username | `spacepost` (the alias `resend` is accepted too, for migrations) |
| Password | Your API key (`sp_live_...`) |

Connect without TLS and upgrade with STARTTLS before you log in; the certificate is valid for `smtp.spacepost.dev`. Implicit TLS (port 465) is not offered yet, so in most clients choose "STARTTLS" or "TLS", not "SSL".

The `From` address must belong to a [verified domain](/domains/adding-and-verifying/). A `sending_access` key is enough; a domain-restricted key can only send from its domain.

## Control headers

Add these headers to your message to use features SMTP has no field for. They are consumed by SpacePost and not delivered to the recipient.

| Header | Example | Effect |
|---|---|---|
| `X-SpacePost-Tags` | `category=welcome, user_id=u_1042` | Adds [tags](/sending/tags/). Comma-separated `name=value` pairs; same character rules as the API. |
| `X-SpacePost-Scheduled-At` | `2026-11-01T09:00:00Z` or `in 1 hour` | [Schedules](/sending/scheduling/) the email (up to 30 days). |

Other `X-*` headers, `List-Unsubscribe`, `List-Unsubscribe-Post`, `In-Reply-To` and `References` are forwarded as custom headers.

## Examples

  **Nodemailer**

    ```js
import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.spacepost.dev",
  port: 25976,
  secure: false, // STARTTLS: the connection is upgraded to TLS before login
  requireTLS: true,
  auth: { user: "spacepost", pass: process.env.SPACEPOST_API_KEY },
});

await transport.sendMail({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Hello over SMTP",
  html: "<p>It works.</p>",
  headers: { "X-SpacePost-Tags": "category=welcome", "X-SpacePost-Scheduled-At": "in 10 minutes" },
});
```
  
  **Python**

    ```python
import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Acme <hello@acme.com>"
msg["To"] = "user@example.com"
msg["Subject"] = "Hello over SMTP"
msg["X-SpacePost-Tags"] = "category=welcome"
msg.set_content("It works.")
msg.add_alternative("<p>It works.</p>", subtype="html")

with smtplib.SMTP("smtp.spacepost.dev", 25976) as s:
    s.starttls()
    s.login("spacepost", os.environ["SPACEPOST_API_KEY"])
    s.send_message(msg)
```
  
  **swaks**

    ```bash
swaks --server smtp.spacepost.dev --port 25976 --tls \
  --auth-user spacepost --auth-password "$SPACEPOST_API_KEY" \
  --from hello@acme.com --to delivered@test.spacepost.dev \
  --header "Subject: Hello" --header "X-SpacePost-Tags: category=test" --body "It works."
```
  

## How messages are mapped

- `To`, `Cc` and `Reply-To` come from the headers. Envelope recipients (`RCPT TO`) that are not in `To` or `Cc` become **Bcc**.
- HTML and text parts are preserved. Attachments, including inline images (`Content-ID`), are supported.
- A message without a subject gets the subject `(no subject)`.
- Each recipient counts against your quota, as with the API.

## Limits and error codes

| Limit | Value |
|---|---|
| Message size | 40 MB, reply `552` |
| Authentication failures | 10 failed attempts per IP in 10 minutes, then blocked |

SMTP replies map the API errors:

| Situation | Reply |
|---|---|
| Daily or monthly quota exceeded | `452` (temporary: your software will retry later) |
| Rate limited | `421` |
| `From` domain not verified | `553` |
| Restricted key, paused team, validation errors, content blocked | `550` |
| Temporary problem on our side | `451` |

> Note:
SMTP has no equivalent of an API `id` in the reply. Find the email in the dashboard or `GET /emails`, and use [webhooks](/webhooks/overview/) for delivery status.

## Framework guides