Email

POST /api/v1/emails

Body parameters (JSON):

Responses: 202 ({ id, status: "queued" }), 200 ({ status: "duplicate", idempotencyKey, id }), 422 (validation), 402 (plan quota), 403 (domain_not_verified), 409 (suppressed).

Example

import { Sending } from "sending-sdk";
 
const sending = new Sending({ apiKey: process.env.SENDING_API_KEY! });
 
const { id } = await sending.emails.send({
  from: "Acme <hello@yourdomain.dev>",
  to: "sara@acme.io",
  subject: "Hello",
  html: "<p>Hey</p>",
  replyTo: "Support <support@yourdomain.dev>",
  idempotencyKey: "hello-sara-001",
});

POST /api/v1/emails/batch

Up to 100 emails in one request. The body is { "emails": [...] } and each item is exactly the body of POST /api/v1/emails, idempotencyKey included.

The outcome is partial, not all-or-nothing: the response is 207 and results is aligned by index with the array you sent, so one invalid address out of 60 does not stop the other 59.

Idempotency applies per item: a retried batch produces no double sends, and items already accepted come back accepted with duplicate: true. For rate limiting purposes the call counts as one request.

const outcome = await sending.emails.sendBatch([
  { from: "Acme <hello@yourdomain.dev>", to: "sara@acme.io", subject: "Hello", html: "<p>hey</p>", idempotencyKey: "b-001" },
  { from: "Acme <hello@yourdomain.dev>", to: "boss@acme.io", subject: "Hello", html: "<p>hey</p>", idempotencyKey: "b-002" },
]);
for (const r of outcome.results) {
  if (r.status === "failed") console.error(`item ${r.index}: ${r.error?.code}`);
}

Response:

{
  "accepted": 2,
  "failed": 1,
  "results": [
    { "index": 0, "status": "accepted", "id": "8f1c…" },
    { "index": 1, "status": "accepted", "id": "0b22…", "duplicate": true },
    { "index": 2, "status": "failed", "error": { "code": "suppressed", "message": "complaint" } }
  ]
}

GET /api/v1/emails/:id

State of one send: use the id returned when you sent it.

const status = await sending.emails.get(id);
console.log(status.status, status.events);

It returns status, metadata (to, from, subject, provider, createdAt, kind: transactional, campaign or automation), the attachments of the send (id, filename, contentType, size), an engagement summary (opensHuman, opensMachine, clicks, contentClicks, lastLinkUrl, bounced, unsubscribed), the links clicked grouped by canonical URL (with role and isContent) and the events timeline (sent, delivered, open, click, bounce, complaint). Every click event carries linkUrl, linkId and linkRole (logo, image, cta, text, social, video, chrome): three clicks on the logo are not interest in the content. Opens count as human only when classification is human: Apple Mail Privacy Protection and Gmail's proxy open every email on their own.

GET /api/v1/emails

The sends of the workspace, newest first, each with the same engagement summary. Same filters as the dashboard list: campaignId, contactId, status (queued, sent, delivered, failed, bounced), engagement (clicked, opened_not_clicked, not_opened among the delivered, bounced, unsubscribed), q on recipient and subject, since (ISO 8601), limit (max 100) and offset. Requires the emails:read scope (or email:send).

// Who clicked in this campaign?
const page = await sending.emails.list({ campaignId, engagement: "clicked", limit: 100 });
console.log(page.total, page.data.map((m) => m.to));