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 API & Integrations 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 → Domain & mailbox "From address" 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 your verified domain — see From address in the API reference for why and for SMTP's looser rule.

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 API & Integrations page for auditing.
  • No existing SMTP relay? Native sending lets MailInApp deliver on your behalf, once your domain is allowlisted and verified.