MOLTED EMAIL

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 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). 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).

Basic usage

Silent capture (no email sent)

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

CLI
molted capture --email user@example.com --list waitlist
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:

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

With confirmation email

Add subject and html/text to send a confirmation:

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."
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:

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

With tags and metadata

Enrich the contact record with tags and arbitrary metadata:

CLI
molted capture --email user@example.com --list beta-users \
  --name "Jane Smith" \
  --tags early-access,landing-page \
  --source form \
  --metadata '{"referrer": "producthunt"}'
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

FieldRequiredDescription
emailYesRecipient email address
listYesThe 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
subjectNoConfirmation email subject. If omitted, no email is sent (silent capture)
htmlNoEmail HTML body. With subject, one of html or text is required (400 otherwise)
textNoEmail plaintext body
nameNoContact display name
tagsNoArray of string tags stored in contact metadata.tags (merged with existing)
doubleOptInNoIf true and list is new, subscription starts as pending. Existing lists use their own double opt-in setting. Default: false
sourceNoAttribution source: form, api, import, manual (400 otherwise). Default: api
metadataNoArbitrary JSON merged into contact metadata

How it works

  1. Resolves the contact the same way list subscribe/unsubscribe 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 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.

  • Contacts: manage contact records directly
  • Lists: create and manage subscriber lists, and double opt-in
  • Sending Email: full send API reference