Skip to content

Transactional email API

Your product has mail of its own: a report is ready, an import failed, a status changed. Send it through Canopus from your own domain, on a stream whose reputation never mixes with your campaigns, and retire the separate email vendor you were paying for it.

From zero to the first email

Four steps, three of which you have already done if your campaigns send.

  1. Verify your sending domain

    Settings, then Sending domain: add your domain, publish the records shown, wait for Verified. Your campaigns already use this.

  2. Enable the transactional stream

    On the same screen, enable the stream. It gets its own subdomain (tx.yourdomain.com) with a few more records to publish, so its reputation lives apart, then set its sender name and address.

  3. Create an API key

    Settings, then API: create a key and copy it immediately; it is shown once and stored hashed. Put it in your server environment, never in client code.

  4. Send the first email

    The curl below, with your key. The response carries an id; GET it to watch the delivery happen.

Authentication

Every request carries your key as a bearer token. Keys belong to one project, start with cnp_live_, and can be revoked at any moment from the API screen; a revoked key answers 401 on its next request.

All three failures (missing, malformed, revoked) answer the same 401 on purpose: the response must not help anyone probe which keys exist.

Authorization: Bearer cnp_live_...

POST /api/v1/emails

Sends one email, synchronously: the 202 comes back once our infrastructure has accepted the message, with the id you will query. One recipient per call, 256 KB per body.

The From is the transactional sender you configured, on your tx. subdomain. You cannot set it per request: the address is what keeps the stream’s reputation apart, and it is configuration, not payload.

to *
One recipient address.
subject *
Up to 300 characters.
html
The HTML body. At least one of html and text is required.
text
The plain-text body. Sending both is best for deliverability.
replyTo
Where replies go, if not the sender.
headers
Extra headers. Only x-* names are kept; everything else is ours to set.
idempotencyKey
Replay shield; the Idempotency-Key header wins when both are given.
curl -X POST https://www.canopushq.io/api/v1/emails \
  -H "Authorization: Bearer $CANOPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-2026-10-04-42" \
  -d '{
    "to": "ada@customer.example",
    "subject": "Your weekly report",
    "html": "<p>Twelve new signups this week.</p>",
    "text": "Twelve new signups this week."
  }'
{
  "id": "0192f3a1-7c2e-7b1a-9f44-3d2a8c1b6e90",
  "status": "sent",
  "to": "ada@customer.example",
  "createdAt": "2026-10-04T09:30:12.000Z"
}

GET /api/v1/emails/{id}

Where one send stands. The status starts at sent, then moves to delivered, bounced or complained as the mailbox provider reports back, usually within seconds. A bounce or complaint carries a detail object with the provider’s reason.

{
  "id": "0192f3a1-7c2e-7b1a-9f44-3d2a8c1b6e90",
  "status": "delivered",
  "to": "ada@customer.example",
  "subject": "Your weekly report",
  "createdAt": "2026-10-04T09:30:12.000Z",
  "occurredAt": "2026-10-04T09:30:14.000Z"
}

Idempotency

Give every send a stable Idempotency-Key (the report id, the event id). A retry with the same key returns the original send instead of sending twice, whatever happened to the first response on its way to you.

This is also the answer to a 500: retry with the same key until you get a 202. The key is scoped to your project, so collisions with other customers cannot happen.

Errors

One shape for every failure: {"error": {"code", "message"}}. The code is the contract; the message is for your logs. Branch on the code, never on the message.

CodeStatusWhat it means, and what to do
unauthorized401The key is missing, malformed or revoked. The response never says which.
invalid_payload422The body is not JSON or does not match the contract. `details` names each field.
payload_too_large413The request body passed 256 KB.
recipient_suppressed422This address hard-bounced or complained before. Sending to it is refused; stop writing to it.
stream_not_ready409The transactional stream is not enabled, not verified, suspended, or has no sender. Fixed in Settings, not in code.
quota_exceeded429The monthly ceiling is reached. `Retry-After` points at the first of next month; upgrading lifts it now.
subscription_required402No active subscription covers this project, so nothing is sent. Choosing a plan, or putting the project back under yours, starts it again.
rate_limited429Too many requests for this key or this address. `Retry-After` says when to come back.
not_found404No such email for this key. An id you did not create looks exactly like one that does not exist.
internal_error500Our side failed. Retry with the same Idempotency-Key: the retry cannot double-send.

Rate limits

  • 120 requests per minute per key on POST, 300 per minute on GET.
  • A 429 carries Retry-After in seconds. Honour it; a tight retry loop only spends your budget faster.
  • These limits serve a product loop. Bulk sending belongs to campaigns, which have their own pipeline, scheduling and unsubscribe machinery.

The monthly quota

Transactional sends count into the same monthly quota as your campaigns: one plan, one number. The difference is what happens at the line: campaigns stop at 100 percent, your product mail keeps sending.

Past the quota you are in a tolerated overage, free of charge, with a notification so you can upgrade. At twice the quota the API answers quota_exceeded: that ceiling exists so a loop in your code cannot run unbounded.

Suppression

An address that hard-bounces or complains is suppressed for your whole project, both streams at once: the address is the fact, not the channel. Further sends to it answer recipient_suppressed.

A marketing unsubscribe does not suppress transactional mail: the person refused your campaigns, not their own password reset or report.

From Node

No SDK needed: the API is one fetch. If you are migrating from an email vendor, this replaces the send call one for one.

const response = await fetch("https://www.canopushq.io/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CANOPUS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `report-${reportId}`,
  },
  body: JSON.stringify({
    to: user.email,
    subject: "Your weekly report",
    html: renderedReport,
  }),
})

if (response.status === 422) {
  const { error } = await response.json()
  if (error.code === "recipient_suppressed") {
    // The address bounced or complained before: stop writing to it.
  }
}