Node SDK

npm install @avelto/sdk

import { Avelto } from "@avelto/sdk";

const avelto = new Avelto(process.env.AVELTO_API_KEY);

const { id } = await avelto.emails.send({
  from: "Acme <[email protected]>",
  to: "[email protected]",
  subject: "Your receipt",
  html: "<p>Thanks for your order.</p>",
});

const avelto = new Avelto(apiKey, {
  baseUrl: "https://api.avelto.dev", // also read from AVELTO_BASE_URL
  timeoutMs: 30_000,                 // per request
  fetch: customFetch,                // any fetch-compatible function
  retry: { maxAttempts: 3, baseDelayMs: 300, maxDelayMs: 5_000 }, // the defaults
});

const { id } = await avelto.emails.send(
  {
    from: "[email protected]",
    to: "[email protected]",
    subject: "Receipt #1042",
    text: "...",
  },
  { idempotencyKey: "receipt-1042" },
);

// On by default: 3 attempts, exponential backoff with jitter.
const avelto = new Avelto(apiKey, { retry: { maxAttempts: 5 } });

// Off, if you run your own retry loop:
const once = new Avelto(apiKey, { retry: { maxAttempts: 1 } });

// After the last attempt the error is thrown as usual:
try {
  await avelto.emails.send({ from, to, subject, text });
} catch (err) {
  if (err instanceof AveltoError && err.status === 429) {
    console.log("rate limited; the server asked for " + err.retryAfterSeconds + "s");
  }
}

const { id } = await avelto.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Your trial ends tomorrow",
  text: "...",
  scheduled_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
});

const { status } = await avelto.emails.cancel(id); // status === "cancelled"

const { results, accepted, failed } = await avelto.emails.sendBatch(
  {
    messages: [
      { from: "[email protected]", to: "[email protected]", subject: "Receipt #1042", text: "..." },
      { from: "[email protected]", to: "[email protected]", subject: "Receipt #1043", text: "..." },
    ],
  },
  { idempotencyKey: "receipts-2026-09-17" },
);

// results[i] lines up with messages[i]; each is accepted or refused on its own.
for (const r of results) {
  if (r.ok) console.log(r.index, r.id);
  else console.error(r.index, r.error.code, r.error.message);
}
console.log(accepted, failed);

const email = await avelto.emails.get(id);
console.log(email.status);                    // "queued" | "scheduled" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "cancelled"
console.log(email.events.map((e) => e.type)); // ["email.queued", "email.sent", "email.delivered"]

let cursor: string | null = null;
do {
  const page = await avelto.emails.list({
    status: "bounced",
    tag: "onboarding",
    limit: 100,
    cursor: cursor ?? undefined,
  });
  for (const e of page.data) console.log(e.id, e.to, e.subject);
  cursor = page.next_cursor;
} while (cursor);

const domain = await avelto.domains.create({ name: "mail.acme.com" });

for (const r of domain.dns_records) {
  console.log(`${r.type}\t${r.name}\t${r.value}\t(${r.purpose})`);
}

// Publish the records, then poll. domains.get re-checks verification on every call until the domain is verified.
let status = domain.status;
while (status === "pending") {
  await new Promise((r) => setTimeout(r, 30_000));
  status = (await avelto.domains.get(domain.id)).status;
}
console.log(status); // "verified" (or "failed")

const { data } = await avelto.domains.list();
await avelto.domains.delete(domain.id);

const template = await avelto.templates.create({
  name: "Welcome",
  subject: "Welcome to Acme, {{name}}",
  html: "<p>Hi {{name}}, thanks for signing up.</p>",
});
console.log(template.slug, template.variables); // "welcome" ["name"]

// Send it: the template supplies the subject and body.
const { id } = await avelto.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  template_slug: "welcome",
  variables: { name: "Jane" },
});

// Every save keeps a version; restore writes an old one forward as a new one.
await avelto.templates.update(template.id, { subject: "Welcome aboard, {{name}}" });
const { data: versions } = await avelto.templates.versions(template.id);
await avelto.templates.restore(template.id, versions[1].version);

const { data } = await avelto.templates.list();
await avelto.templates.get(template.id);
await avelto.templates.delete(template.id);

const endpoint = await avelto.webhooks.create({
  url: "https://acme.com/hooks/avelto",
  // optional; defaults to all eight event types
  events: ["email.delivered", "email.bounced", "email.complained"],
});
console.log(endpoint.secret);

import express from "express";
import { verifyWebhookSignature, type WebhookPayload } from "@avelto/sdk";

const app = express();

const secret = process.env.AVELTO_WEBHOOK_SECRET;

app.post("/hooks/avelto", express.raw({ type: "application/json" }), async (req, res) => {
  const body = req.body.toString("utf8");
  const signature = req.header("Avelto-Signature");
  const ok = await verifyWebhookSignature(secret, body, signature);
  if (!ok) return res.status(400).send("invalid signature");

  const event = JSON.parse(body) as WebhookPayload;
  if (event.type === "email.bounced") {
    console.log("bounced", event.data.email_id, event.data.details);
  }
  res.sendStatus(200);
});

const { data: endpoints } = await avelto.webhooks.list();
const endpoint = await avelto.webhooks.get(endpointId);

const { data: deliveries, next_cursor } = await avelto.webhooks.listDeliveries(endpointId, { limit: 50 });
const failed = deliveries.find((d) => d.status === "failed");
if (failed) await avelto.webhooks.retryDelivery(endpointId, failed.id);

await avelto.webhooks.delete(endpointId);

const { data, next_cursor } = await avelto.suppressions.list({ limit: 100 });
data.forEach((s) => console.log(s.email_address, s.reason)); // "bounce" | "complaint" | "manual"

await avelto.suppressions.create({ email_address: "[email protected]" });
await avelto.suppressions.delete("[email protected]");

const summary = await avelto.account.get();
console.log(summary.key.mode, summary.key.scopes);     // "test" ["emails:send", ...]
console.log(summary.sandbox.domain, summary.sandbox.recipients);
console.log(summary.domains, summary.webhooks, summary.templates);

import { AveltoError } from "@avelto/sdk";

try {
  await avelto.emails.send({
    from: "[email protected]",
    to: "[email protected]",
    subject: "Hi",
    text: "Hi",
  });
} catch (err) {
  if (err instanceof AveltoError) {
    console.error(err.status, err.code, err.message, err.details);
  } else {
    throw err;
  }
}

import type { SendEmailRequest, Email, EmailSummary, Domain, DnsRecord, WebhookEndpoint, WebhookPayload, Suppression, ErrorCode } from "@avelto/sdk";