Quickstart

This guide takes you from zero to a sent email in about five minutes. You'll create an API key, register a sending domain, and make your first POST /v1/emails request.

1. Create an API key

From the dashboard, create a key scoped to emails:send. The full key is shown exactly once and starts with ms_live_ — store it in your secrets manager immediately. MailStack only ever stores a prefix and a hash, so a lost key can't be recovered (just create a new one).

2. Add and verify a sending domain

You can only send from a domain you've verified. Register one with POST /v1/domains, publish the returned DNS records (DKIM, SPF, and a custom MAIL FROM record), then call POST /v1/domains/{id}/verify to confirm propagation. See Domains & DKIM for the full walkthrough.

3. Send your first email

Make a request to the send endpoint. A successful call returns 202 Accepted with a message id and a status of queued:

POST /v1/emails

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 Acme",
    "html": "<h1>Hi there 👋</h1><p>Thanks for signing up.</p>"
  }'

The response looks like:

{
  "id": "8f3a1c2e-77d4-4a9b-9b1e-3c0a5d6e7f88",
  "status": "queued"
}

4. Check the status

Poll GET /v1/emails/{id} to follow the message through its lifecycle — queued → sent, or bounced/failed with an error message. See Sending email for the full message shape.

Next steps

Core concepts — domains, keys, suppression, webhooks, templates.
API reference — every endpoint with request/response details.
Webhooks — react to delivery and bounce events.