Vela API reference

Keys

Send the key as a bearer token. A key carries a permission: full sends and reads, sending only sends, and read only reads. It also carries an expiry you choose when you create it, or no expiry at all. Revoking a key refuses every request made with it from that moment.

curl https://vela.novacraft.africa/api/v1/emails \
  -H "Authorization: Bearer vela_live_…"

Sending

curl -X POST https://vela.novacraft.africa/api/v1/emails \
  -H "Authorization: Bearer vela_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Your invoice is ready",
    "html": "<p>Thanks, it is attached below.</p>",
    "attachments": [
      { "filename": "invoice.pdf", "content": "JVBERi0xLjcK…" }
    ]
  }'

# → { "id": "b7c3…" }

Each attachment carries its bytes as base64 content; Vela does not fetch a path. Give one a content_id and it travels inline, drawn wherever the html says <img src="cid:…">. Up to 28 MB in total, and a scheduled send cannot carry files yet.

Errors

Suppressions

An address that bounces for good or reports spam is suppressed, and Vela will not send to it again. Bounces and complaints also land on a list every workspace shares, because one sender reputation carries all of them. Check recipients before you send to show the reason in your own interface instead of finding a skipped address afterwards.

curl -X POST https://vela.novacraft.africa/api/v1/suppressions/check \
  -H "Authorization: Bearer vela_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "addresses": ["[email protected]", "[email protected]"] }'

# → { "object": "list", "data": [
#     { "address": "[email protected]", "reason": "bounce",
#       "detail": "smtp; 550 5.1.1 user unknown",
#       "createdAt": "2026-10-08T08:33:14.545Z", "shared": true } ] }

Inbound

Point the domain's MX at Vela and every message is accepted, checked against SPF, DKIM and DMARC, parsed, and written to each destination that matches. Four kinds: webhook, postgres, libsql and s3. A delivery that fails is retried with backoff and every attempt keeps the status it got back.

Webhook payload

POST https://api.yourapp.com/hooks/mail
svix-id:         msg_…
svix-timestamp:  1757980800
svix-signature:  v1,<base64>

{
  "type": "mail.received",
  "data": {
    "id": "…",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Invoice #4821",
    "spf": "PASS",
    "dkim": "PASS",
    "dmarc": "PASS"
  }
}

Verifying the signature

Vela signs with the Svix scheme, so an existing Resend or Svix verifier works unchanged. Concatenate the id, the timestamp and the raw body with dots, HMAC-SHA256 it with the destination secret, and compare in constant time.

const signed = `${svixId}.${svixTimestamp}.${rawBody}`
const expected = createHmac('sha256', secret).update(signed).digest('base64')
// header is "v1,<expected>"

Turn on includeRaw for a destination and the original MIME travels with the payload, attachments included.

MCP

The same keys open an MCP server. Give an agent a read key to read the mailbox. Over MCP a key never both reads and sends: a full key is read-only here, and send_email takes a sending key. Mail an agent reads is written by outside senders, and an agent that could also send would let that mail tell it what to send.

{
  "mcpServers": {
    "vela": {
      "url": "https://vela.novacraft.africa/api/mcp",
      "headers": { "Authorization": "Bearer vela_live_…" }
    }
  }
}

Dashboard routes

These authenticate with your signed-in session rather than an API key, and back the dashboard itself. They are documented so you can script against the same contract from a browser context.