mailinapp
Documentation menu

Quickstart

The transactional Send API lets your own backend trigger an email — the same way you'd call Brevo, SendGrid or Postmark's send endpoint. It's a natural fit for OTPs, receipts and alerts, and it can also fire a project you've designed in the studio, with your own data standing in for a contact row.

Mint a key

Under Developers in the dashboard, hit Create key and give it a name (e.g. "Production backend", "Staging"). The full key — mia_live_... — is shown exactly once. Store it somewhere safe; MailInApp only keeps a hash, so there's no way to retrieve it again. If you lose it, revoke it and mint a new one.

Keys are scoped to your account, not to a single project — one key can trigger any project you own. Create as many as you like (one per environment or integration is a common pattern) and revoke any of them independently at any time.

Send #1: freeform

For a plain transactional email — no studio project involved — supply the HTML and text yourself:

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your one-time code",
    "html": "<p>Your code is 123456</p>",
    "text": "Your code is 123456"
  }'

A successful call returns:

{ "id": "abc123", "status": "sent" }

Send #2: template

This is the actual differentiator: design an email visually in the studio — fallback engine, interactive blocks, merge tags — then trigger it from your own signup, checkout or support code with mergeData standing in for a data-source row:

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{
    "to": "[email protected]",
    "projectId": "your-project-id",
    "mergeData": { "name": "Ada", "orderId": "12345" }
  }'

Find projectId in the studio URL for the project (/studio/<projectId>). mergeData fields resolve into the project's {{field}} merge tags exactly like a contact row would. The recipient gets a personal, signed live view link same as any other send — interactive blocks (polls, ratings, forms) work, and every response flows into that project's normal Responses view and webhook deliveries, attributed to this specific API call.

The Idempotency-Key header is optional but recommended for anything triggered by a retryable operation (a checkout webhook, a queue consumer) — see idempotency in the API reference.

Overriding the sender

Both send types default to your account's configured sender identity — the Settings → Domains "From address" card if you're on native (SES) sending, or your SMTP relay's from address otherwise. Add from to override it for one call, e.g. a multi-brand account sending as a specific team:

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your one-time code",
    "html": "<p>Your code is 123456</p>",
    "text": "Your code is 123456",
    "from": { "email": "[email protected]", "name": "Your Sales Team" }
  }'

from.email is required whenever from is present at all (no name-only override); from.name is optional. On native (SES) sending, from.email must be an address at one of your verified domains — see From address in the API reference for why and for SMTP's looser rule.

If you've already saved a sender identity in the dashboard, pass its id as senderId instead of repeating the address/name inline — see the API reference for both fields.

Next steps

  • Full request/response shapes, type semantics, rate limits and error codes: API reference.
  • Recent calls made with your keys — including status and any error — show up on the Developers page for auditing.
  • No existing SMTP relay? Native sending lets MailInApp deliver on your behalf, once your domain is allowlisted and verified.
  • Want an AI agent to build or edit your emails instead of calling the API directly? The same key also authenticates the MCP server, so Claude Desktop, Claude Code, or any other MCP client can do it for you by chat.