# Email Capture

Source: https://molted.email/docs/email-capture

One-call contact collection with list subscription and optional confirmation email.

Email capture handles the entire "collect an email" flow in one API call: upsert contact, subscribe to list, and optionally send a confirmation email. Covers waitlists, beta signups, newsletter captures, and lead magnets.

It is an agent route: your agent (or your own backend) calls it with its API key when someone signs up. There is no public form or publishable key: a browser posts to your own server, which calls capture with its key. To subscribe people when another service (Clerk, Stripe, a form provider) sends a webhook, use an [inbound webhook mapping](https://molted.email/docs/inbound-hooks.md) with a `subscribe_to_list` action instead.

## Endpoint

```
POST https://mailbox.molted.email/v1/agent/capture
```

The key needs `send` on a mailbox: the confirmation email goes out from that mailbox (a mailbox-scoped key's own mailbox, otherwise your [default mailbox](https://molted.email/docs/mailboxes.md#default-mailbox)). On `api.molted.email` the body also carries your `tenantId`; the CLI adds it from your credentials. There is no MCP capture tool; MCP clients use `subscribe_to_list` (see [Lists](https://molted.email/docs/lists.md)).

## Basic usage

### Silent capture (no email sent)

Collect an email address and subscribe to a list without sending any confirmation:

```bash title="CLI"
molted capture --email user@example.com --list waitlist
```

```bash title="curl"
curl -X POST https://mailbox.molted.email/v1/agent/capture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "list": "waitlist"
  }'
```

Response:

```json
{
  "contactId": "uuid",
  "listId": "uuid",
  "subscriptionStatus": "active",
  "emailStatus": null,
  "requestId": null
}
```

### With confirmation email

Add `subject` and `html`/`text` to send a confirmation:

```bash title="CLI"
molted capture --email user@example.com --list waitlist \
  --subject "You're on the waitlist!" \
  --body "<p>Thanks for signing up. We'll notify you when we launch.</p>" \
  --text "Thanks for signing up."
```

```bash title="curl"
curl -X POST https://mailbox.molted.email/v1/agent/capture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "list": "waitlist",
    "subject": "You'\''re on the waitlist!",
    "html": "<p>Thanks for signing up.</p>",
    "text": "Thanks for signing up."
  }'
```

Response:

```json
{
  "contactId": "uuid",
  "listId": "uuid",
  "subscriptionStatus": "active",
  "emailStatus": "queued",
  "requestId": "uuid"
}
```

### With tags and metadata

Enrich the contact record with tags and arbitrary metadata:

```bash title="CLI"
molted capture --email user@example.com --list beta-users \
  --name "Jane Smith" \
  --tags early-access,landing-page \
  --source form \
  --metadata '{"referrer": "producthunt"}'
```

```bash title="curl"
curl -X POST https://mailbox.molted.email/v1/agent/capture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "list": "beta-users",
    "name": "Jane Smith",
    "tags": ["early-access", "landing-page"],
    "source": "form",
    "metadata": { "referrer": "producthunt" }
  }'
```

## Field reference

| Field | Required | Description |
| - | - | - |
| `email` | Yes | Recipient email address |
| `list` | Yes | The list's name, matched exactly (an archived list doesn't count). Subscribes to this list; auto-creates it with that name if it doesn't exist |
| `subject` | No | Confirmation email subject. If omitted, no email is sent (silent capture) |
| `html` | No | Email HTML body. With `subject`, one of `html` or `text` is required (`400` otherwise) |
| `text` | No | Email plaintext body |
| `name` | No | Contact display name |
| `tags` | No | Array of string tags stored in contact `metadata.tags` (merged with existing) |
| `doubleOptIn` | No | If `true` and list is new, subscription starts as `pending`. Existing lists use their own double opt-in setting. Default: `false` |
| `source` | No | Attribution source: `form`, `api`, `import`, `manual` (`400` otherwise). Default: `api` |
| `metadata` | No | Arbitrary JSON merged into contact metadata |

## How it works

1. **Resolves the contact** the same way [list subscribe/unsubscribe](https://molted.email/docs/lists.md#address-matching) do: matched case/whitespace-insensitively, with `+alias`/Gmail-dot variants collapsing onto one contact (whichever was seen first). Merges `name`, `tags`, and `metadata` into that contact. The email is stored lowercased and trimmed.
2. **Resolves list** by name. If the list doesn't exist, auto-creates it with `type: newsletter` and the requested `doubleOptIn` setting.
3. **Subscribes** the contact to the list. Idempotent: skips if already subscribed. If the address had previously unsubscribed from this list, it stays unsubscribed rather than being reactivated (see below). On a [double opt-in](https://molted.email/docs/lists.md#double-opt-in) list the subscription starts `pending`, and the list's own `list.subscribe.pending` event (with the `confirmationUrl`) fires, separately from any email capture sends.
4. **Sends email** (if `subject` is provided) via the `_default` template, unless the address stayed unsubscribed in step 3. Dedupe key: `capture:{list}:{email}` prevents duplicate confirmation sends.
5. Returns a combined result with contact, list, subscription, and email status.

## Edge cases

- **Already subscribed**: returns success with current subscription status. Still sends email if `subject` is provided (unless deduped).
- **Previously unsubscribed from this list**: `subscriptionStatus` is `"unsubscribed"` with `reason: "previously_unsubscribed"`, and no email is sent even if `subject` is provided. On a double opt-in list, capture may still re-open the subscription as `pending` and re-send the confirmation: it still requires a click-through before going `active`.
- **Suppressed contact**: the contact is still upserted, but it is not subscribed, and a confirmation send comes back `emailStatus: "blocked"`.
- **Any blocked send** (suppressed, no verified sender, a quota): `emailStatus` is `"blocked"`, and the capture itself still succeeds.
- **List exists with different doubleOptIn**: uses the list's existing setting, ignores the request's `doubleOptIn` flag.
- **Invalid email** or a missing `list`: returns `400`.

## CLI reference

```
molted capture [options]

Options:
  --email <email>      Recipient email address (required)
  --list <list>        List slug to subscribe to (creates list if it does not exist) (required)
  --subject <subject>  Confirmation email subject (if omitted, no email is sent)
  --body <body>        Email HTML body (used when --subject is set)
  --text <text>        Email plaintext body
  --name <name>        Contact display name
  --tags <tags>        Comma-separated tags (e.g. early-access,landing-page)
  --double-opt-in      Require double opt-in confirmation
  --source <source>    Attribution source: form, api, import, manual (default: "api")
  --metadata <json>    Arbitrary JSON metadata
```

`--body` is sent as `html`.

## Related

- [Contacts](https://molted.email/docs/contacts.md): manage contact records directly
- [Lists](https://molted.email/docs/lists.md): create and manage subscriber lists, and double opt-in
- [Sending Email](https://molted.email/docs/sending-email.md): full send API reference
