Quickstart

You need three things: an account, a verified domain, and an API key. The whole point of this walkthrough is the last step, where you go and look at what actually happened.

1. Verify a domain

Mail only leaves OutSend for domains you have proven you control. Add your domain in the dashboard and you will get three records to publish:

Publish them, then press Verify. Propagation is usually minutes but DNS is DNS — if it has not gone through, the domain stays pending rather than failing.

Pick your sending region while you are here. It is set per domain, and it determines where your mail is processed.

See Domains and DNS for what each record does and how to check them.

2. Create an API key

Keys are scoped either to the whole workspace or to a single domain. Use a domain-scoped key for anything that only ever sends from one address — if it leaks, the blast radius is one domain.

Every key records a last_used_at timestamp, which is the fastest way to find keys you forgot to delete.

3. Send a message

curl -X POST https://app.getoutsend.com/api/v1/emails \
  -H "Authorization: Bearer $OUTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-42" \
  -d '{
    "from": "alerts@yourdomain.com",
    "to": "you@example.com",
    "subject": "First send",
    "html": "<p>Hello from OutSend.</p>",
    "text": "Hello from OutSend.",
    "stream": "transactional"
  }'

{ "id": 10482, "stream": "transactional" }

Keep that id. It is how you pull the trace back.

Already have a mailer configured? Skip the API entirely and point it at the SMTP relay instead — same sending path, same events.

4. Read the trace

This is the step that matters. Open the message in the dashboard and you will see every event recorded against it, each with the receiving provider’s own response:

09:14:02.114  queued          accepted · idempotency-key welcome-42
09:14:02.380  sent            handed to AWS SES · us-east-1
09:14:03.921  delivery_delay  450 4.7.1 Not accepted, try again later
09:16:41.552  delivery        250 2.0.0 OK — accepted after retry

A deferral followed by a delivery is a completely normal shape, and it is invisible on a platform that only reports a final percentage. Being able to see it is the difference between knowing your mail is fine and assuming it.

5. Get the events pushed to you

Polling is fine for a quickstart, not for production. Register a webhook and OutSend will POST each event to you as it arrives, signed with a secret unique to that endpoint.

Where to go next

• API reference — every field, error, and limit
• Events reference — all eight event types and what they mean
• Self-hosting — run the whole thing yourself