Avelto
View as MarkdownOpen in Claude

Send email from Node.js

Five steps: install the SDK, create a test key, send to the sandbox, read the log, then verify a domain so you can send to anyone.

1. Install

The SDK needs Node 20 or later and has no runtime dependencies. The scripts below use top-level await, so set "type": "module" in your package.json if it is not already.

shell
npm install @avelto/sdk

2. Create an API key

Sign in, open API keys in the dashboard and create a test key. It starts with av_test_. Export it so the samples can read it:

shell
export AVELTO_API_KEY=av_test_...

3. Send your first email

TypeScript
// send.tsimport { Avelto, AveltoError } from "@avelto/sdk";const avelto = new Avelto(process.env.AVELTO_API_KEY!);try {  const { id } = await avelto.emails.send({    from: "you@sandbox.avelto.dev",    to: "delivered@sandbox.avelto.dev",    subject: "Hello from Avelto",    text: "It works.",  });  console.log(id); // "9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10"} catch (err) {  if (err instanceof AveltoError) {    console.error(err.status, err.code, err.message);  } else {    throw err;  }}
shell
npx tsx send.ts

The API answers 201 Created with the email id. Anything else is an AveltoError, and the route passes its status, code and message back as the same error envelope.

HTTP
HTTP/1.1 201 CreatedContent-Type: application/json{ "id": "9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10" }

4. Check the log

Fetch the email by id. status moves from queued to sent to delivered, and events records each step: email.queued, email.sent, email.delivered.

TypeScript
const email = await avelto.emails.get(id);console.log(email.status); // "queued", then "sent", then "delivered"for (const e of email.events) {  console.log(e.type, e.occurred_at);}
JSON
{  "id": "9c1f4a52-6f6e-4b8f-9b8e-2e1a5c7d3f10",  "mode": "test",  "from": "you@sandbox.avelto.dev",  "to": ["delivered@sandbox.avelto.dev"],  "subject": "Hello from Avelto",  "status": "delivered",  "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": ["delivered@sandbox.avelto.dev"] },      "occurred_at": "2026-09-17T10:12:06.000Z"    }  ]}

5. Verify a domain

Add a domain, publish the DNS records it returns (an ownership TXT, an SPF TXT and a DMARC TXT, then three DKIM CNAMEs once the ownership record is found), then poll domains.get until status is verified. Use a subdomain such as mail.acme.com.

TypeScript
// verify-domain.tsimport { Avelto } from "@avelto/sdk";const avelto = new Avelto(process.env.AVELTO_API_KEY!);const domain = await avelto.domains.create({ name: "mail.acme.com" });const print = (d: typeof domain) => {  for (const r of d.dns_records) {    console.log(`${r.type}\t${r.name}\t${r.value}\t(${r.purpose})`);  }};print(domain); // the ownership record first, with SPF and DMARC// Publish the records, then poll. domains.get re-checks DNS on every call.// Once the ownership record is found, the DKIM records appear: publish those too.let current = domain;while (current.status === "pending") {  await new Promise((r) => setTimeout(r, 30_000));  const next = await avelto.domains.get(domain.id);  if (next.ownership_verified && !current.ownership_verified) print(next);  current = next;}console.log(current.status); // "verified" or "failed"

Once the domain is verified, switch AVELTO_API_KEY to a live key (av_live_) and change from to an address on it, such as hello@mail.acme.com. Nothing else changes.

Next

  • Send email: every field, attachments, tags, scheduling and idempotency.
  • Webhooks: get events pushed to your app.
  • Test mode: test keys, the sandbox sender and the simulator addresses.