Mail API docs

Send email from your own domain over REST. JSON in, JSON out.

Get an API key

Authentication

Create a key in Mail API → API keys and send it in the Authorization header. Keep keys secret and only use them on your server.

Authorization: Bearer cq_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Send only keys can send and schedule. Full access keys can also change or cancel scheduled emails, read and list emails and manage templates. A Send only key gets 403 insufficient_permission for those.

Every answer is JSON. Field names are snake_case and times are ISO 8601 in UTC.

SDKs

The Node.js client is @cartiqo/mail on npm: Node 18+, Deno, Bun or any runtime with fetch, with types and no dependencies. It adds an Idempotency-Key to each send and retries dropped connections, 429 and 5xx (not 502) safely.

npm install @cartiqo/mail
import { CartiqoMail } from "@cartiqo/mail";

const mail = new CartiqoMail(); // reads CARTIQO_API_KEY
const { id, status } = await mail.emails.send({
  from: "Shop <orders@yourshop.dk>",
  to: "kunde@example.com",
  template: "signup-code",
  variables: { name: "Sofie", code: "482 913" },
});

// Full access key: every bounced email, page by page
for await (const e of mail.emails.iterate({ status: "bounced" })) console.log(e.id, e.status);

Failed calls throw a CartiqoError with status, code and the message from Errors. It also has verifyWebhook for webhooks, the 14 template presets (presets, renderTemplate) and a command line: npx @cartiqo/mail --help.

There's no Python package yet: call the API over HTTP, as in Examples.

Send an email

POST https://api.cartiqo.app/v1/emails

The from address must be on a domain you've verified in Domains.

FieldTypeDescription
fromstring“orders@yourshop.dk” or “Shop <orders@yourshop.dk>”. Required.
tostring or string[]Up to 50 recipients. Required.
subjectstringUp to 255 characters. Required, unless the template has one.
htmlstringHTML body. Send html, text, both, or a template.
textstringPlain-text body. Made from html when you leave it out.
templatestringA template's id (tpl_…) or alias. See Templates.
variablesobjectValues for the template's {{variables}}.
scheduled_atstringISO 8601 time to send it, up to 30 days ahead. See Schedule an email.
tagsstring[]Up to 10 labels shown in your logs and webhooks.
reply_tostringWhere replies go.

Response

{ "id": "em_7Hq2aB9xYz1cD4eF", "status": "sent" }

Add an Idempotency-Key header so a retry can't send the email twice. See Idempotency.

If some recipients are on your suppression list, the email goes to the others and the response lists the ones left out in suppressed. If all of them are, nothing is sent and you get a 422 with "status": "suppressed".

Idempotency

Networks drop answers. Send an Idempotency-Key header with POST /v1/emails and POST /v1/emails/batch, and a retry with the same key gets the first answer back instead of sending again. Use a UUID, or something from your side like receipt-Q-4F8K: up to 255 visible ASCII characters.

Idempotency-Key: 4f1c2a7e-9b3d-4c55-8e21-6d0f7a9b1c3e
When you retry with the same keyYou get
The first request finishedIts answer and status again, with the header Idempotency-Replayed: true. Nothing is sent.
The first request is still running409 idempotency_in_progress. Retry in a moment.
The body is different422 idempotency_key_reused. Use a new key for a new email.
The first request failed with an errorIt runs again, so you can fix the request and keep the key.

Keys are kept for 24 hours per account. The logs show each email's key; in a batch, email n shows key#n.

Send a batch

POST https://api.cartiqo.app/v1/emails/batch sends up to 100 emails in one call. The body is a JSON array of emails (or { "emails": [...] }), each with the same fields as a single send.

Every email is checked first. If one is wrong, nothing is sent and the error names it, like emails[3]: “bob@” isn't a valid email address. Each email counts once towards your monthly quota.

[
  { "from": "Shop <orders@yourshop.dk>", "to": "anna@example.org", "subject": "Your receipt", "text": "Thanks!" },
  { "from": "Shop <orders@yourshop.dk>", "to": "lars@example.net", "template": "receipt", "variables": { "order": "Q-4F8K" } }
]

Response

{
  "data": [
    { "id": "em_x7SwEeBsQ7IXTELl", "status": "sent" },
    { "id": "em_SSu2PY0BmqsICmio", "status": "sent" }
  ]
}

Schedule an email

Add scheduled_at to a send or batch email, with a time zone, up to 30 days ahead: "2026-10-23T09:00:00+02:00" or "2026-10-23T07:00:00Z". The email is checked and counted now, and sent within a few seconds of that time. If the from domain is no longer verified then, it fails.

{ "id": "em_J40dbugkxmA6T1Ek", "status": "scheduled", "scheduled_at": "2026-10-23T07:00:00.000Z" }

Change or cancel it while it's still scheduled, with a Full access key:

PATCH https://api.cartiqo.app/v1/emails/:id          { "scheduled_at": "2026-10-24T07:00:00Z" }
POST  https://api.cartiqo.app/v1/emails/:id/cancel   → { "id": "em_…", "status": "canceled" }

A canceled email doesn't count towards your quota. Once it's sent, both answer 409 not_scheduled. You can also cancel from the logs in the dashboard.

Templates

Save a subject, html and text in Mail API → Templates, then send with its id or alias and your values:

{
  "from": "Shop <hello@yourshop.dk>",
  "to": "kunde@example.com",
  "template": "signup-code",
  "variables": { "name": "Anna", "code": "482 913", "order": { "id": "Q-4F8K" } }
}
In the templateBecomes
{{name}}The value. In html it's escaped, so < and & are safe.
{{{name}}}The value as is, for html you build yourself.
{{name|there}}The value, or “there” when it's missing.
{{order.id}}A value inside an object.

A variable with no value and no fallback stops the send with 422 missing_variables, so nobody gets “Hi ,”. A subject in the request replaces the template's. Don't send html or text with a template.

Manage templates over the API

With a Full access key. :id is the template's id (tpl_…) or its alias.

GET    https://api.cartiqo.app/v1/templates                → { "data": [template, …] }
GET    https://api.cartiqo.app/v1/templates/:id
POST   https://api.cartiqo.app/v1/templates                { "name", "alias"?, "subject", "html"?, "text"? }   → 201 template
PATCH  https://api.cartiqo.app/v1/templates/:id            only the fields you change; null clears html or text
DELETE https://api.cartiqo.app/v1/templates/:id            → { "id": "tpl_…", "deleted": true }
POST   https://api.cartiqo.app/v1/templates/:id/render     { "variables": { … } }   → subject, html, text, missing_variables
{
  "id": "tpl_Qm3xY8aB2cD4eF6g",
  "name": "Sign-up code",
  "alias": "signup-code",
  "subject": "Your code: {{code}}",
  "html": "<p>Hi {{name|there}}, your code is <b>{{code}}</b>.</p>",
  "text": null,
  "variables": ["code", "name"],
  "created_at": "2026-10-20T08:12:00.000Z",
  "updated_at": "2026-10-28T14:03:00.000Z"
}

render fills in a template without sending it, so you can check your variables before going live. Aliases are unique per account (409 alias_taken), and an account has up to 100 templates.

Get an email

GET https://api.cartiqo.app/v1/emails/:id needs a Full access key.

{
  "id": "em_7Hq2aB9xYz1cD4eF",
  "from": "Shop <orders@yourshop.dk>",
  "to": ["kunde@example.com"],
  "subject": "Your order Q-4F8K",
  "status": "delivered",
  "error": null,
  "tags": ["receipt"],
  "template": null,
  "created_at": "2026-10-19T09:41:00.000Z",
  "scheduled_at": null,
  "sent_at": "2026-10-19T09:41:01.000Z",
  "delivered_at": "2026-10-19T09:41:03.000Z",
  "events": [
    { "type": "sent", "recipient": null, "detail": null, "created_at": "2026-10-19T09:41:01.000Z" },
    { "type": "delivered", "recipient": "kunde@example.com", "detail": "250 2.0.0 OK", "created_at": "2026-10-19T09:41:03.000Z" }
  ]
}

How long we keep emails

What an email said (its html and text) is kept for 30 days after it's sent, so you can read it in the logs, and is then deleted. Who it went to, the subject, its status and events stay in your logs and in this API. Scheduled emails keep their content until they go out.

List emails

GET https://api.cartiqo.app/v1/emails needs a Full access key. Newest first, without events.

QueryDescription
statusOne of the statuses.
tagEmails with this tag.
toEmails to this address.
qSearches recipients and subjects, or an exact email id.
since, untilISO 8601 dates or times: created at or after since, before until.
limit1 to 100. Default 20.
starting_afterThe next_cursor of the previous page.
GET https://api.cartiqo.app/v1/emails?status=bounced&since=2026-10-01&limit=2

{
  "data": [
    { "id": "em_Bj7ENpphj5Au02pd", "from": "Shop <orders@yourshop.dk>", "to": ["kunde@example.com"], "subject": "Your order Q-4F8K", "status": "bounced", "error": "Permanent (General): smtp; 550 5.1.1 user unknown", "tags": ["receipt"], "template": "tpl_Qm3xY8aB2cD4eF6g", "created_at": "…", "scheduled_at": null, "sent_at": "…", "delivered_at": null },
    { "id": "em_x7SwEeBsQ7IXTELl", … }
  ],
  "has_more": true,
  "next_cursor": "em_x7SwEeBsQ7IXTELl"
}

A cursor that isn't one of your emails answers 400 invalid_cursor.

Statuses

StatusMeans
scheduledWaiting for its scheduled_at.
queuedAccepted and being sent right now.
sentHanded to the recipient's mail servers.
deliveredThe recipient's server accepted it.
bouncedIt couldn't be delivered. The error says why.
complainedThe recipient marked it as spam.
failedWe couldn't send it.
canceledA scheduled send you canceled.
suppressedNot sent, because every recipient is suppressed.

With several recipients, the status is the worst outcome so far: one bounce makes it bounced even when the others got it. The events list says what happened for each recipient.

Webhooks

Add an https URL in Mail API → Webhooks and we POST an event to it whenever something happens to your emails. Answer with any 2xx within 10 seconds. Anything else is retried after 30 seconds, 2 and 10 minutes, then with longer gaps for about a day. The dashboard shows every delivery, what your server answered, and lets you resend one.

EventWhen
email.scheduledA send with scheduled_at was accepted, or moved to another time.
email.sentWe handed the email to the receiving side's mail servers.
email.deliveredThe recipient's server accepted it. One event per recipient batch.
email.delivery_delayedThe recipient's server is slow or greylisting. We keep trying.
email.bouncedIt couldn't be delivered. Hard bounces are suppressed.
email.complainedThe recipient marked it as spam. The address is suppressed.
email.failedWe couldn't send it at all. The error says why.
email.canceledA scheduled send was canceled.
email.suppressedNot sent: every recipient is on your suppression list.
POST /webhooks/cartiqo
Content-Type: application/json
Cartiqo-Event-Id: evt_0bEynYBMeEfqgPmvpoIF
Cartiqo-Event-Type: email.bounced
Cartiqo-Signature: t=1792656000,v1=5f2c…

{
  "id": "evt_0bEynYBMeEfqgPmvpoIF",
  "type": "email.bounced",
  "created_at": "2026-10-22T11:27:37.000Z",
  "data": {
    "email_id": "em_Bj7ENpphj5Au02pd",
    "from": "Shop <orders@yourshop.dk>",
    "to": ["kunde@example.com"],
    "subject": "Your order Q-4F8K",
    "tags": ["receipt"],
    "bounce": {
      "type": "Permanent",
      "subtype": "General",
      "recipients": [{ "address": "kunde@example.com", "diagnostic": "smtp; 550 5.1.1 user unknown" }],
      "suppressed": true
    }
  }
}

Events can arrive more than once and out of order. Use id to skip ones you've handled.

Check the signature

Cartiqo-Signature holds a Unix timestamp t and v1, the hex HMAC-SHA256 of t + "." + body with your webhook's signing secret (whsec_…). Compute it over the raw body, compare in constant time, and reject old timestamps so a captured request can't be replayed.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body as a string, before JSON.parse
export function verifyCartiqo(rawBody, header, secret, toleranceSec = 300) {
  const t = /t=(\d+)/.exec(header ?? "")?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(header ?? "")?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
import hashlib, hmac, re, time

def verify_cartiqo(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    t = re.search(r"t=(\d+)", header or "")
    v1 = re.search(r"v1=([0-9a-f]+)", header or "")
    if not t or not v1 or abs(time.time() - int(t.group(1))) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(v1.group(1), expected)

Suppressions

When an address hard-bounces or marks your email as spam, we add it to your suppression list and stop sending to it. That keeps your domain's reputation, and everyone else's deliveries, healthy. Soft bounces, like a full mailbox, aren't suppressed. See and edit the list in Mail API → Suppressions; you can also add addresses by hand, for example people who unsubscribed elsewhere.

Errors

Errors return a JSON body with a readable error that says how to fix it, and a stable code to branch on. Every /v1 error has a code; we may add new ones, so keep a default branch.

{ "error": "Verify yourshop.dk in Mail API → Domains first. Its DNS records aren't confirmed yet.", "code": "domain_not_verified" }
HTTPcodeWhat to do
400invalid_inputFix the field named in the message.
400invalid_from / invalid_recipientFix the from address, or the recipient named in the message.
400too_many_recipientsUp to 50 per email. Use a batch for more.
400invalid_cursor / invalid_idempotency_keyPass the next_cursor you got, or a key of up to 255 visible ASCII characters.
401missing_api_key / invalid_api_keySend a valid key in the Authorization header.
403domain_not_added / domain_not_verifiedAdd and verify the from domain in Domains.
403insufficient_permissionUse a Full access key to list or read emails, change or cancel scheduled ones, and manage templates.
403template_limitDelete a template you don't use.
403no_planPick a Mail plan in Settings → Plan.
404email_not_found / template_not_foundCheck the id (or alias). It belongs to another account or was deleted.
409not_scheduledThe email was already sent or canceled.
409alias_takenPick another alias.
409idempotency_in_progressThe first request with this key is still running. Retry in a moment.
422idempotency_key_reusedUse a new Idempotency-Key for a different request.
422missing_variablesAdd the named variables, or give them a fallback.
422recipient_suppressedEvery recipient is suppressed. Remove them from Suppressions if you're sure.
429rate_limitedToo many requests. Wait the seconds in Retry-After.
429monthly_quotaWait for the reset on the 1st, or move to a bigger plan.
502send_failedSending failed upstream. The email is in your logs with its id; retry after a minute.

Limits

One Mail plan covers the inbox and the Mail API. API emails and domains are per team: everyone in a Business team sends from the same monthly quota. Prices include VAT; a year costs 10 months.

PlanPriceDomainsPeopleStorageAPI emails a month
Mail Starter€4.99/mo115 GB5,000
Mail Pro€9.99/mo3115 GB25,000
Mail Business€19.99/mo10Up to 1515 GB each100,000

Extra storage is €0.99 a month per 10 GB. Over the monthly quota you get 429 monthly_quota; without a plan, 403 no_plan. During the early access everyone has Mail Business for free, and plans aren't on sale yet. Accounts have up to 100 templates and 10 webhooks. Bought lists and spam are not allowed; accounts with high bounce or complaint rates are paused.

Rate limits

Counted per API key, per minute:

EndpointRequests a minute
POST /v1/emails, GET /v1/emails/:id600
GET /v1/emails300
Cancel, reschedule, templates120
POST /v1/emails/batch60 (up to 6,000 emails)

Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (seconds until the window resets). Over the limit you get 429 rate_limited with Retry-After. @cartiqo/mail waits and retries for you.

Examples

curl

curl -X POST https://api.cartiqo.app/v1/emails \
  -H "Authorization: Bearer $CQ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"from":"Shop <orders@yourshop.dk>","to":"kunde@example.com","subject":"Your order Q-4F8K","html":"<p>Thanks for your order.</p>"}'

Node.js without the SDK

const res = await fetch("https://api.cartiqo.app/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CQ_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Shop <orders@yourshop.dk>",
    to: "kunde@example.com",
    subject: "Your order Q-4F8K",
    html: "<p>Thanks for your order.</p>",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.id);

Python (requests)

import os, requests

r = requests.post(
    "https://api.cartiqo.app/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['CQ_KEY']}"},
    json={
        "from": "Shop <orders@yourshop.dk>",
        "to": "kunde@example.com",
        "subject": "Your order Q-4F8K",
        "text": "Thanks for your order.",
    },
)
r.raise_for_status()
print(r.json()["id"])