Outsend API reference

curl https://api.outsend.dev/v1/emails \
  -H "Authorization: Bearer outsend_xxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

curl -X POST https://api.outsend.dev/v1/emails \
  -H "Authorization: Bearer outsend_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Hello",
    "html": "<p>It works 🎉</p>"
  }'

# → { "id": "msg_...", "status": "sent" }

Authorization: Bearer outsend_xxxxxxxxxxxxxxxx

{ "email": "sam@example.com", "name": "Sam" }

{
  "filename": "invoice.pdf",
  "content": "<base64>",
  "contentType": "application/pdf"
}

{ "id": "evt_...", "type": "delivered", "timestamp": "2026-07-08T...", "payload": {} }

{ "id": "msg_...", "status": "sent" }

# status ∈ sent | pending | scheduled | failed
# On failed, an "error" field is present.

{
  "data": [
    { "id": "...", "from": "...", "subject": "...", "status": "sent",
      "createdAt": "...", "sentAt": "..." }
  ],
  "hasMore": true,
  "nextCursor": "<id>"
}

{
  "data": {
    "id": "...", "from": "...", "to": [...], "subject": "...",
    "html": "...", "text": "...", "status": "sent",
    "createdAt": "...", "sentAt": "...",
    "events": [
      { "id": "...", "type": "sent", "timestamp": "..." },
      { "type": "delivered" }, { "type": "opened" }, { "type": "clicked" }
    ],
    "attachments": [ { "id": "...", "filename": "...", "contentType": "..." } ]
  }
}

{ "emails": [ { ...sendParams }, { ...sendParams } ] }

# → { "data": [ { "id": "...", "status": "sent" }, { "status": "failed", "error": "..." } ] }

{ "valid": true, "domain": "example.com", "mx": ["mx1.example.com"] }
{ "valid": false, "reason": "No MX records found" }

curl -X POST .../v1/emails \
  -H "Idempotency-Key: order-123" ...

# POST
{ "email": "spam@bad.com", "reason": "manual" }
# reason ∈ manual | unsubscribe | bounce | complaint
# → { "ok": true, "email": "spam@bad.com" }

# GET → { "data": [ { "email": "...", "reason": "bounce", "source": "webhook", "createdAt": "..." } ] }
# Filter a single address with ?email=...

# DELETE → { "ok": true }

# POST
{ "name": "Newsletter", "description": "Weekly product updates" }
# → 201 { "data": { "id": "cl...", "name": "Newsletter", "description": "...", "createdAt": "..." } }

# GET /v1/lists?limit=100&cursor=...
# → { "data": [ { "id": "cl...", "name": "Newsletter", "contactCount": 432, ... } ], "hasMore": false, "nextCursor": null }

# GET /v1/lists/:id → { "data": { ..., "contactCount": 432 } }

# POST
{ "email": "jane@acme.com", "name": "Jane", "listIds": ["cl..."] }
# → 201 { "data": { "id": "...", "email": "jane@acme.com", "name": "Jane", "unsubscribed": false, ... } }

# GET /v1/contacts?limit=100&listId=...&unsubscribed=false&cursor=...
# → { "data": [...], "hasMore": true, "nextCursor": "..." }
# Filters: email, listId, unsubscribed (true|false). limit ≤ 1000.

# GET /v1/contacts/:id → { "data": { ..., "lists": [{ "id": "...", "name": "..." }] } }

# POST
{ "name": "July launch", "templateId": "cl...", "listId": "cl...", "from": "you@yourdomain.com", "scheduledAt": "2026-08-01T09:00:00Z" }
# → 201 { "data": { "id": "...", "status": "scheduled", "sentCount": 0, "failedCount": 0, ... } }
# status ∈ draft | scheduled | sending | sent | paused

# GET /v1/campaigns?status=sent&limit=50&cursor=...
# → { "data": [...], "hasMore": true, "nextCursor": "..." }

# GET /v1/campaigns/:id
# → { "data": { ..., "messageCount": 1234, "template": {...}, "list": {...} } }

# → { "data": {
#   "total": 5210, "sent": 5000, "failed": 210, "delivered": 4980,
#   "opened": 1200, "clicked": 300, "bounced": 18, "complained": 2,
#   "deliveryRate": 99.6, "bounceRate": 0.4, "complaintRate": 0,
#   "openRate": 24, "clickRate": 6,
#   "series": [ { "day": "2026-07-01", "sent": 100, "failed": 2, "bounced": 0, "delivered": 99 }, ... ],
#   "statuses": [ { "status": "sent", "count": 5000 }, ... ],
#   "topFrom": [ { "from": "you@yourdomain.com", "count": 5210 } ]
# }}

# POST to register
{ "url": "https://your.app/hooks/outsend", "events": ["delivered","bounced"], "active": true }
# events empty = all events. Returns the webhook incl. its signing "secret" (shown once).

# Delivered event body
{ "type": "delivered", "data": { "messageId": "..." }, "timestamp": 1751980000000 }

import crypto from "node:crypto";
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
// compare to req.headers["x-outsend-signature"]

1. Verify your sending domain in SES (Easy DKIM + custom MAIL FROM).
2. Create a Configuration Set → add an SNS destination with event types:
   Send, Delivery, Bounce, Complaint, Open, Click.
3. Create an SNS topic; subscribe your endpoint as HTTPS:
   https://api.outsend.dev/v1/webhooks/ses
   (Outsend auto-confirms the SubscriptionConfirmation the first time it arrives.)
4. Set OUTSEND_WEBHOOK_SECRET for the manual-test / Lambda-forwarding path.

curl -X POST https://api.outsend.dev/v1/webhooks/ses \
  -H "x-outsend-webhook-secret: $OUTSEND_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"eventType":"Delivery","mail":{"commonHeaders":{"messageId":"<your-message-id@yourdomain>"}},"delivery":{"timestamp":"2026-07-09T00:00:00Z"}}'

{
  "from": "user@example.com",
  "to": "reply@yourdomain.com",
  "subject": "Re: ...",
  "text": "...",
  "html": "...",
  "organizationId": "<only for shared-secret mode>"
}

{ "report": "<base64 gzip xml>", "gzipped": true }

# →
{
  "data": {
    "orgName": "google.com",
    "email": "noreply-dmarc-support@google.com",
    "domain": "yourdomain.com",
    "rangeStart": "...", "rangeEnd": "...",
    "records": [
      { "sourceIp": "192.0.2.1", "count": 5, "disposition": "none", "dkim": "pass", "spf": "pass" }
    ]
  }
}