Quickstart

This guide takes you from zero to a delivered email.

1. Get an API key

Create a key in the dashboard under API Keys. Keys are shown once — copy it somewhere safe. Live keys are prefixed sk_live_; the dashboard can also issue TEST_KEY_… keys for development.

2. Verify a sending domain

You can only send from a domain you've verified. Register it, then publish the DNS records SendMailOS returns (one DKIM TXT, an SPF TXT + MX on send.{domain}, and a tracking CNAME). See Verify a domain.

3. Send an email

curl https://api.sendmailos.com/v1/emails \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "You <[email protected]>",
    "to": "[email protected]",
    "subject": "Hello from SendMailOS",
    "html": "<h1>It works.</h1><p>Your first send is on its way.</p>"
  }'

const res = await fetch('https://api.sendmailos.com/v1/emails', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_your_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    from: 'You <[email protected]>',
    to: '[email protected]',
    subject: 'Hello from SendMailOS',
    html: '<h1>It works.</h1>',
  }),
});
const email = await res.json();

The response contains the email id and its status. from accepts a "Name <[email protected]>" string; to accepts a string, an array of strings, or an array of { email, name } objects.

4. Track what happened

• Poll GET /v1/emails/{id} for the current state.
• Or subscribe to webhooks to receive email.delivered, email.opened, email.clicked, and email.bounced events as they happen.

Next steps