Quickstart

Send your first email in three steps. No domain setup needed: every account gets a sandbox sender and simulator recipients.

1. Get an API key

av_test_… runs the full pipeline without sending anything. Events and webhooks still fire.
av_live_… sends real email.

Every request carries the key as a bearer token: Authorization: Bearer av_test_….

2. Send an email

The request below sends from your sandbox domain (sandbox.avelto.dev) to the delivered@ simulator address, which always reports a delivery. The sandbox sender and the simulator addresses both work with live and test keys.

curl -X POST https://api-staging.avelto.dev/v1/emails \
  -H "Authorization: Bearer av_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from Avelto",
    "text": "It works."
  }'

The API answers 201 Created with the email id:

HTTP

HTTP/1.1 201 Created
Content-Type: application/json

{ "id": "9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10" }

3. Watch it move

Fetch the email to see its status and every event so far.

curl https://api-staging.avelto.dev/v1/emails/9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10 \
  -H "Authorization: Bearer av_test_..."

JSON

{
  "id": "9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10",
  "mode": "test",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "cc": [],
  "bcc": [],
  "reply_to": null,
  "subject": "Hello from Avelto",
  "tags": [],
  "status": "delivered",
  "scheduled_at": null,
  "created_at": "2026-09-17T10:12:04.000Z",
  "updated_at": "2026-09-17T10:12:06.000Z",
  "html": null,
  "text": "It works.",
  "headers": {},
  "unsubscribe_url": null,
  "idempotency_key": null,
  "attachments": [],
  "domain_id": null,
  "ses_message_id": "test-9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10",
  "error": null,
  "events": [
    {
      "id": "e1f0c3a4-8b2d-4c6e-9a1f-5d7b3e2c8a90",
      "type": "email.queued",
      "payload": {},
      "occurred_at": "2026-09-17T10:12:04.000Z"
    },
    {
      "id": "a7c2e9d1-3f4b-4a8e-b6c0-2d9e1f7b5c34",
      "type": "email.sent",
      "payload": { "test": true, "ses_message_id": "test-9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10" },
      "occurred_at": "2026-09-17T10:12:06.000Z"
    },
    {
      "id": "c4b8d2f6-7e1a-4d3c-8f9b-6a2e0c5d1b78",
      "type": "email.delivered",
      "payload": { "test": true, "recipients": ["[email protected]"] },
      "occurred_at": "2026-09-17T10:12:06.000Z"
    }
  ]
}

Status goes queued, then sent, then delivered (or bounced, complained, failed). The events array is the full log.

Limits on a new account

For its first 7 days every account is capped at 100 live emails a day and 5 domains, whatever the plan. A live send past the daily cap is refused with 429 plan_limit until midnight UTC. Test sends do not count, so a load test belongs on a test key. Details on Plans and limits.

Pick your language once

Every request in the docs is shown in the same seven languages. Node uses the SDK (npm install @avelto/sdk); the others are plain HTTPS with a common client for the language, so anything that can make an HTTPS request works. Choose a tab once and every page remembers it, or set your stack in the sidebar. The quickstarts repeat these steps inside Next.js, Express, Fastify, Django, Laravel, Rails and more.

What next

Send email covers every field: multiple recipients, attachments, headers, tags, scheduling and idempotency.
Domains walks through sending from your own domain. Until a domain is verified, the sandbox sender only delivers to your own verified account email and the simulator addresses.
Webhooks push events to your app as they happen.
The API reference lists every route, field and error code.