API Keys Guide

CenterLeap exposes a small, focused REST API for transactional email. Each API key is bound to exactly one mailbox and authenticates with a standard Authorization: Bearer cl_live_… header — the same pattern as Resend, Stripe, OpenAI, etc.

The complete surface

Scopes

Pick the narrowest scope that does the job. Changing a key's scope means rotating it, so it's worth getting right the first time.

1. Go to Dashboard → Mail → Settings
2. Open the domain and select the mailbox the key should send/read as
3. Click the "API Keys" tab
4. Pick a scope: Send only (default), Read only, or Full access
5. Pick an expiration: Never (default), 30 / 60 / 90 days, 1 year, or a custom date
6. Click Create — copy the key now, or reveal it again later from the row

Key format

cl_live_ prefix + 48 hex characters. The first 12 hex characters are also stored unencrypted as a lookup prefix — do not paste the prefix anywhere public.

The send endpoint is Resend-compatible — most SDKs that target Resend will work by swapping the base URL.

cURL

curl -X POST 'https://mail-api.centerleap.com/v1/emails' \
  -H 'Authorization: Bearer cl_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "recipient@example.com",
    "subject": "Hello from CenterLeap",
    "html": "<p>Hello!</p>"
  }'

Node.js (fetch)

const res = await fetch('https://mail-api.centerleap.com/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CENTERLEAP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'hello@yourdomain.com',
    to: 'recipient@example.com',
    subject: 'Hello from CenterLeap',
    html: '<p>This email was sent via REST API.</p>',
  }),
});

const { id } = await res.json();
console.log('queued', id);

Python (requests)

import os, requests

res = requests.post(
    'https://mail-api.centerleap.com/v1/emails',
    headers={
        'Authorization': f"Bearer {os.environ['CENTERLEAP_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'from': 'hello@yourdomain.com',
        'to': 'recipient@example.com',
        'subject': 'Hello from CenterLeap',
        'html': '<p>Hello!</p>',
    },
)
res.raise_for_status()
print('queued', res.json()['id'])

Request body

Response (200)

{ "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794" }

The id is the internal message UUID. The message is queued for outbound delivery — the response returns as soon as the message hits the queue, before the SMTP relay.

Attachments

{
  "from": "hello@yourdomain.com",
  "to": "recipient@example.com",
  "subject": "Your invoice",
  "html": "<p>Invoice attached.</p>",
  "attachments": [
    {
      "filename": "invoice-2026-05.pdf",
      "content": "JVBERi0xLjQKJ…",
      "content_type": "application/pdf"
    }
  ]
}

content is the base64-encoded file bytes (no data: URI prefix). If content_type is omitted, the server defaults to application/octet-stream.

List messages

Query parameters:

• folder — message folder. Defaults to inbox. Conventional values: inbox, archive, trash, sent, spam. Free-form text — whatever value you PATCH to a message becomes a valid folder filter.
• limit — page size, 1–100. Defaults to 50.
• before — ISO-8601 timestamp. Returns messages with received_atstrictly less than this. Pass the previous page's next_cursor to paginate.

curl 'https://mail-api.centerleap.com/v1/inbox/messages?folder=inbox&limit=20' \
  -H 'Authorization: Bearer cl_live_xxx'

{
  "messages": [
    {
      "id": "9c2…",                       // internal UUID
      "message_id": "<…@example.com>",   // RFC 5322 Message-ID
      "from": "sender@example.com",
      "to": "you@yourdomain.com",
      "subject": "Hello",
      "received_at": "2026-05-16T00:48:46Z",
      "folder": "inbox",
      "is_read": false,
      "is_starred": false,
      "has_attachments": false,
      "size_bytes": 4821
    }
    // …
  ],
  "next_cursor": "2026-05-15T22:11:03Z"   // null on the last page
}

Fetch one message

Returns the full parsed headers plus text and html bodies. Use the id (internal UUID) from the list response.

{
  "id": "9c2…",
  "message_id": "<…@example.com>",
  "headers": { "from": "…", "to": "…", "subject": "…", "date": "…" },
  "text": "Plain-text body…",
  "html": "<p>HTML body…</p>",
  "received_at": "2026-05-16T00:48:46Z",
  "folder": "inbox",
  "is_read": false,
  "is_starred": false,
  "has_attachments": false,
  "size_bytes": 4821
}

Requires full_access scope. Send any subset of the three writable fields — omitted fields are left unchanged. Returns { ok: true, no_op: true } when the body has no fields.

curl -X PATCH 'https://mail-api.centerleap.com/v1/inbox/messages/9c2…' \
  -H 'Authorization: Bearer cl_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "is_read": true }'

curl -X PATCH 'https://mail-api.centerleap.com/v1/inbox/messages/9c2…' \
  -H 'Authorization: Bearer cl_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "is_starred": true, "folder": "archive" }'

Body

Unlike GET, PATCH does not require the mailbox to be on plaintext tier — it only flips DB columns, never reads ciphertext.

Two cheap health probes that identify a key without sending anything. Use them to verify a key works during integration or from a deploy-time smoke test.

curl 'https://mail-api.centerleap.com/v1/emails/_ping' \
  -H 'Authorization: Bearer cl_live_xxx'

{
  "ok": true,
  "mailbox": "noreply@yourdomain.com",
  "scope": "send_only",
  "rate_limit_per_hour": 1000
}

Every error response carries a name machine code and a human-readable message. Validation errors include a Zod issues array.

POST /v1/emails is rate-limited per-key, per-hour. The default is 1000 sends/hour; you can set a different value when creating a key. The current limit is returned in /v1/emails/_ping as rate_limit_per_hour.

When you hit the limit you get 429 rate_limited with the limit value in the body:

{
  "name": "rate_limited",
  "message": "Hourly send quota exceeded",
  "limit": 1000
}

The bucket resets at the wall-clock hour boundary, not 60 minutes from your first send. The /v1/inbox/* reads and PATCHes are not currently rate-limited per-key (the nginx vhost has a global rate limit as a backstop).

The CenterLeap SMTP shim accepts SMTP AUTH where the password is your cl_live_* key. It parses the message, then forwards it to POST /v1/emails internally — the same code path, just over SMTP. No separate SMTP password.

import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg['From'] = 'hello@yourdomain.com'   # must match the key's mailbox
msg['To'] = 'recipient@example.com'
msg['Subject'] = 'Hello from CenterLeap'
msg.set_content('Sent via SMTP shim.')

with smtplib.SMTP('mail.centerleap.com', 587) as smtp:
    smtp.starttls()
    smtp.login('centerleap', os.environ['CENTERLEAP_API_KEY'])
    smtp.send_message(msg)

SMTP-shim sends are subject to the same scope and rate-limit rules as REST sends. The Fromheader must match the key's mailbox exactly.

Key storage

Keys are encrypted at rest with AES-256-GCM. The encryption key is derived per-row via HKDF-SHA256(server-secret, row-salt, info, 32), so compromise of one row doesn't cascade. Authentication does a prefix lookup, decrypts, and constant-time compares — no plaintext is ever logged.

Attribution

Optional X-CenterLeap-Actor request header lets you attribute a send to a downstream end-user in your own system (e.g. {"user_id":"u_123","email":"buyer@example.com"}). The header is stored opaquely on the audit row — useful when one of your customers reports an unexpected email.