Sending email

const { data, error } = await coss.email.send(
  {
    from: "Acme <hello@acme.com>",
    to: ["ada@example.com", "Grace Hopper <grace@example.com>"],
    cc: "team@acme.com",
    reply_to: "support@acme.com",
    subject: "Your invoice",
    html: "<p>Your invoice is attached to your account.</p>",
    text: "Your invoice is attached to your account.",
    headers: { "X-Entity-Ref-ID": "invoice-123" },
    tags: [{ name: "invoice_id", value: "invoice-123" }],
    category: "billing",
  },
  { idempotencyKey: "invoice-123" },
);

Sends return HTTP 202 with status: "queued". A background worker hands the email to the provider. Follow delivery with coss.email.get() or the email.sent / email.failed webhooks. Emails are kept for 45 days (see data retention).

Scheduling, rescheduling and cancellationCopy Anchor Link

Pass scheduled_at as an ISO 8601 timestamp with a time zone offset, up to 30 days ahead. The response is HTTP 202 with status: "scheduled"; the worker checks for due emails every five seconds and rechecks the sender domain and suppression list before sending. A past timestamp uses the normal queue. Send quotas are charged when the schedule is accepted.

const { data: scheduled } = await coss.email.send({
  from: "hello@acme.com",
  to: "ada@example.com",
  subject: "Your reminder",
  text: "See you tomorrow!",
  scheduled_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
});
if (scheduled) {
  // Send it a day later instead…
  await coss.email.reschedule(scheduled.id, {
    scheduled_at: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
  });
  // …or not at all.
  await coss.email.cancel(scheduled.id);
}

Rescheduling moves a scheduled email to a new time, again at most 30 days from now, and emits email.rescheduled with the new and previous times in data.reschedule. A time that is not in the future sends the email within seconds; the email's current time returns it unchanged, without an event. Only scheduled_at can change: to change the content, cancel and send again. Rescheduling does not charge the send quota again.

Canceling changes the status to canceled and emits email.canceled; repeating the cancellation returns the same email. Once dispatch starts, cancellation returns 422 email_not_cancelable and rescheduling 422 email_not_reschedulable (as does rescheduling a canceled email). Scheduling emits email.scheduled. These events describe the whole email. Suspending an organization holds its scheduled emails until the suspension is lifted. Attachment bytes remain stored while an email is scheduled and are deleted when it is sent, fails, or is canceled.

AddressesCopy Anchor Link

from, to, cc, bcc and reply_to take "user@example.com" or "Display Name <user@example.com>". Each recipient field takes one address or an array of up to 50.

With a live key, from must use a verified domain of your organization. Sandbox keys accept any from.

ContentCopy Anchor Link

subject is required. Provide html, text, or both: sending both lets mail clients pick, and improves deliverability.

Headers and tagsCopy Anchor Link

• headers: up to 15 custom headers. Names are case-insensitive, and reserved names such as subject are rejected.
• tags: up to 50 name/value pairs (letters, digits, _ and -) for your own filtering. They are included in webhook payloads.

CategoriesCopy Anchor Link

category says what kind of email this is, such as "billing" or "marketing" (letters, digits, _ and -). Recipients suppressed for that category, or for every email, are skipped. It is stored on the email and included in webhook payloads.

Sending in batchesCopy Anchor Link

coss.email.sendBatch() sends up to 100 emails in one request. Each email takes the same fields as coss.email.send(), including scheduled_at, attachments and tracking, and they can have different senders and recipients.

const { data, error } = await coss.email.sendBatch(
  [
    {
      from: "Acme <notifications@acme.com>",
      to: "ada@example.com",
      subject: "Your weekly summary",
      html: "<p>Hi Ada, here is your week.</p>",
      category: "digest",
    },
    {
      from: "Acme <notifications@acme.com>",
      to: "grace@example.com",
      subject: "Your weekly summary",
      html: "<p>Hi Grace, here is your week.</p>",
      category: "digest",
    },
  ],
  { idempotencyKey: "weekly-digest-2026-10-10" },
);

The response is HTTP 202 with an email_batch whose data lists the emails in the order you passed them. Each email has the batch's id as batch_id, and is delivered and reported on (with webhooks) on its own.

A batch is all or nothing. If any email is invalid, nothing is sent and the error's issues name it by position, such as emails.3.to. The same goes for an unverified sender domain, which is reported as param: "emails.3.from". One idempotency key covers the whole batch. The batch's recipients count against the send quota together: a batch with more recipients than the quota allows at once is refused with no Retry-After, so split it into smaller batches. The 40 MB request size limit applies to the whole batch.

Retrying safelyCopy Anchor Link

Every send carries an Idempotency-Key. The SDK generates one per call and reuses it across its automatic retries; pass your own (such as invoice-123) to stay safe across process restarts too. For 24 hours, repeating a request with the same key returns the original email instead of sending again. See idempotency.