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.
| Field | Type | Description |
|---|---|---|
| from | string | “orders@yourshop.dk” or “Shop <orders@yourshop.dk>”. Required. |
| to | string or string[] | Up to 50 recipients. Required. |
| subject | string | Up to 255 characters. Required, unless the template has one. |
| html | string | HTML body. Send html, text, both, or a template. |
| text | string | Plain-text body. Made from html when you leave it out. |
| template | string | A template's id (tpl_…) or alias. See Templates. |
| variables | object | Values for the template's {{variables}}. |
| scheduled_at | string | ISO 8601 time to send it, up to 30 days ahead. See Schedule an email. |
| tags | string[] | Up to 10 labels shown in your logs and webhooks. |
| reply_to | string | Where 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 key | You get |
|---|---|
| The first request finished | Its answer and status again, with the header Idempotency-Replayed: true. Nothing is sent. |
| The first request is still running | 409 idempotency_in_progress. Retry in a moment. |
| The body is different | 422 idempotency_key_reused. Use a new key for a new email. |
| The first request failed with an error | It 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 template | Becomes |
|---|---|
{{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.
| Query | Description |
|---|---|
| status | One of the statuses. |
| tag | Emails with this tag. |
| to | Emails to this address. |
| q | Searches recipients and subjects, or an exact email id. |
| since, until | ISO 8601 dates or times: created at or after since, before until. |
| limit | 1 to 100. Default 20. |
| starting_after | The 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
| Status | Means |
|---|---|
| scheduled | Waiting for its scheduled_at. |
| queued | Accepted and being sent right now. |
| sent | Handed to the recipient's mail servers. |
| delivered | The recipient's server accepted it. |
| bounced | It couldn't be delivered. The error says why. |
| complained | The recipient marked it as spam. |
| failed | We couldn't send it. |
| canceled | A scheduled send you canceled. |
| suppressed | Not 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.
| Event | When |
|---|---|
email.scheduled | A send with scheduled_at was accepted, or moved to another time. |
email.sent | We handed the email to the receiving side's mail servers. |
email.delivered | The recipient's server accepted it. One event per recipient batch. |
email.delivery_delayed | The recipient's server is slow or greylisting. We keep trying. |
email.bounced | It couldn't be delivered. Hard bounces are suppressed. |
email.complained | The recipient marked it as spam. The address is suppressed. |
email.failed | We couldn't send it at all. The error says why. |
email.canceled | A scheduled send was canceled. |
email.suppressed | Not 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" }| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_input | Fix the field named in the message. |
| 400 | invalid_from / invalid_recipient | Fix the from address, or the recipient named in the message. |
| 400 | too_many_recipients | Up to 50 per email. Use a batch for more. |
| 400 | invalid_cursor / invalid_idempotency_key | Pass the next_cursor you got, or a key of up to 255 visible ASCII characters. |
| 401 | missing_api_key / invalid_api_key | Send a valid key in the Authorization header. |
| 403 | domain_not_added / domain_not_verified | Add and verify the from domain in Domains. |
| 403 | insufficient_permission | Use a Full access key to list or read emails, change or cancel scheduled ones, and manage templates. |
| 403 | template_limit | Delete a template you don't use. |
| 403 | no_plan | Pick a Mail plan in Settings → Plan. |
| 404 | email_not_found / template_not_found | Check the id (or alias). It belongs to another account or was deleted. |
| 409 | not_scheduled | The email was already sent or canceled. |
| 409 | alias_taken | Pick another alias. |
| 409 | idempotency_in_progress | The first request with this key is still running. Retry in a moment. |
| 422 | idempotency_key_reused | Use a new Idempotency-Key for a different request. |
| 422 | missing_variables | Add the named variables, or give them a fallback. |
| 422 | recipient_suppressed | Every recipient is suppressed. Remove them from Suppressions if you're sure. |
| 429 | rate_limited | Too many requests. Wait the seconds in Retry-After. |
| 429 | monthly_quota | Wait for the reset on the 1st, or move to a bigger plan. |
| 502 | send_failed | Sending 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.
| Plan | Price | Domains | People | Storage | API emails a month |
|---|---|---|---|---|---|
| Mail Starter | €4.99/mo | 1 | 1 | 5 GB | 5,000 |
| Mail Pro | €9.99/mo | 3 | 1 | 15 GB | 25,000 |
| Mail Business | €19.99/mo | 10 | Up to 15 | 15 GB each | 100,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:
| Endpoint | Requests a minute |
|---|---|
| POST /v1/emails, GET /v1/emails/:id | 600 |
| GET /v1/emails | 300 |
| Cancel, reschedule, templates | 120 |
| POST /v1/emails/batch | 60 (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"])