API reference / API-key auth

Emails

Send transactional email — single, batch, and personalized bulk sends — plus pre-send lint, scheduling, cancellation, and status lookups.

POST /v1/emails

API key emails:send

Sends one email. The from address must belong to a verified sending domain. Provide html and/or text, or a published templateId. The to, cc, and bcc fields are comma- or semicolon-separated address lists. Returns 202 Accepted.

Request body

{
  "from": "hello@yourdomain.com",
  "fromName": "Acme",
  "to": "user@example.com",
  "cc": null, "bcc": null, "replyTo": null,
  "subject": "Welcome",
  "html": "<p>Hi {{name}}</p>",
  "text": "Hi",
  "templateId": null,
  "variables": { "name": "Sam" },
  "tags": "welcome",
  "sendAt": null
}

Response

{ "id": "8f3a1c2e-...", "status": "queued" }

curl https://api.mailstack.voostack.com/v1/emails \
  -H "Authorization: Bearer ms_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "subject": "Welcome to MailStack",
    "html": "<h1>Hi there 👋</h1>"
  }'

POST /v1/emails/batch

API key emails:send

Body is { "emails": [ EmailObject, … ] } (max 100). Each item is validated independently — the batch can partially succeed.

Request body

{ "emails": [ { "from": "...", "to": "...", "subject": "...", "html": "..." } ] }

Response

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    { "index": 0, "id": "...", "status": "queued" },
    { "index": 1, "status": "rejected", "error": "Recipient is suppressed." }
  ]
}

POST /v1/emails/bulk

API key emails:send

One shared base message plus a recipients array with per-recipient subject/variable overrides (max 100). Much smaller payload than repeating the whole message per recipient.

Request body

{
  "from": "hello@yourdomain.com",
  "subject": "Hi {{name}}",
  "html": "<p>Hello {{name}}</p>",
  "recipients": [
    { "to": "ada@example.com", "variables": { "name": "Ada" } },
    { "to": "bo@example.com",  "variables": { "name": "Bo" } }
  ]
}

Response

{ "accepted": 2, "rejected": 0, "results": [ ... ] }

POST /v1/emails/lint

API key emails:send

Runs a pre-send lint: authentication alignment (SPF/DKIM), content checks, and a 0–100 score with concrete fixes. Nothing is queued, sent, or billed.

Request body

{ "from": "hello@yourdomain.com", "to": "user@example.com", "subject": "Hi", "html": "<p>Hi</p>" }

Response

{
  "score": 86,
  "rating": "good",
  "passed": true,
  "authentication": { "domain": "yourdomain.com", "domainVerified": true, "dkim": true, "alignedMailFrom": true },
  "issues": [ { "severity": "warning", "code": "BODY_NO_TEXT", "message": "No plain-text part.", "fix": "Add a text body." } ]
}

GET /v1/emails

API key emails:send

Query params: test (true = Dev Inbox, false = live, omit for both) and limit (1–200, default 50).

Response

[ { "id": "...", "toEmail": "user@example.com", "subject": "Welcome", "status": 2, "queuedAt": "..." } ]

GET /v1/emails/{id}

API key emails:send

Get a message and its current status.

Response

{
  "id": "8f3a1c2e-...",
  "fromEmail": "hi@you.com", "toEmail": "user@example.com",
  "subject": "Welcome",
  "status": 2,
  "providerMessageId": "0102018f...",
  "queuedAt": "2026-06-18T10:00:00Z",
  "sentAt": "2026-06-18T10:00:02Z"
}

POST /v1/emails/{id}/cancel

API key emails:send

Cancel a scheduled (future-dated) message before it dispatches.

Response

{ "id": "8f3a1c2e-...", "status": 8 }

SDKs

Prefer a typed client? The Emails endpoints are covered by the official Node, .NET, Go, and Flutter/Dart SDKs.