API Reference

The Kerabie Mail REST API lets you send emails, manage mailboxes, contacts, calendar events, and more. Available on every plan tier, including Free — generate a key under API Keys in the sidebar.

Webhooks docs →Partner API →Zapier →n8n →Make →MCP / Claude agents →llms.txt (for AI agents) →

Authentication

API requests are authenticated with an API key in the X-API-Key header — not Authorization: Bearer (that's used for browser/mobile session tokens instead, obtained via /auth/login, not for API keys). Generate keys with the send scope under API Keys in the sidebar — available on every plan tier, including Free.

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Sending isn't rate-limited by requests-per-minute — each mailbox has its own daily send quota (with an hourly sub-limit to catch bursts) that scales with the mailbox owner's plan, visible via GET /subscriptions/me. Exceeding it returns 429. Mailboxes connected over plain IMAP relay through your own external provider and aren't subject to this quota at all.

API keys

Manage keys programmatically, or from API Keys in the sidebar. These management endpoints themselves are authenticated with your browser/mobile session, not an API key.

GEThttps://api.kerabie.email/api-keys

List your API keys. Never returns the raw key — only key_prefix, which is shown once at creation.

POSThttps://api.kerabie.email/api-keys

Create a key. Returns the full raw key exactly once — store it now, it can't be retrieved again.

Parameter	Type	Required	Description
name	string	required	A label for you — not sent anywhere
scopes	string[]	optional	Defaults to ["send"]. See scopes below
expires_at	string	optional	ISO 8601 datetime — the key stops working after this
allowed_ips	string[]	optional	IPs/CIDRs allowed to use this key (e.g. "203.0.113.0/24"). Omit to allow all
blocked_ips	string[]	optional	IPs/CIDRs denied even if also in allowed_ips — checked first

Scopes

send, mailboxes:read, mailboxes:write, domains:read, domains:write, webhooks, contacts:read, contacts:write. Hosting partners also have partner:* scopes — see the Partner API docs.

Response 201

{
  "id": 42,
  "name": "Production",
  "key": "ker_9f8a...",
  "key_prefix": "ker_9f8a",
  "scopes": ["send", "mailboxes:read"],
  "allowed_ips": null,
  "blocked_ips": null,
  "expires_at": null,
  "created_at": "2026-05-17T10:00:00Z"
}

PATCHhttps://api.kerabie.email/api-keys/{id}

Update IP restrictions or revoke. name/scopes/expires_at can't be changed after creation — create a new key instead.

Parameter	Type	Required	Description
allowed_ips	string[]	optional	Replaces the allowlist — pass [] to clear it
blocked_ips	string[]	optional	Replaces the blocklist — pass [] to clear it
is_active	boolean	optional	Set false to revoke without deleting the record

DELETEhttps://api.kerabie.email/api-keys/{id}

Revoke a key (soft delete — sets is_active=false).

GEThttps://api.kerabie.email/api-keys/{id}/usage

Request counts for this key — informational, not billing.

Response 200

{
  "today": 12,
  "last_7_days": 340,
  "last_30_days": 1204,
  "daily": [{ "date": "2026-05-17", "count": 12 }, ...]
}

Errors

All errors return JSON with a detail field.

{ "detail": "Incorrect password." }

Code	Meaning
200	Success
201	Created
204	Deleted (no body)
400	Bad request — check payload
401	Missing or invalid API key
403	Feature not available on your plan
404	Resource not found
422	Validation error — check field types
429	Rate limit exceeded
500	Server error — contact support

Send email

POSThttps://api.kerabie.email/mail/send

Send an email from a mailbox you own — inline content, or a saved template. Attachments are base64-encoded.

Parameter	Type	Required	Description
from_email	string	required	Sender address (must be a mailbox you own)
to	string[]	required	Recipient email addresses (max 50)
cc	string[]	optional	CC recipients
bcc	string[]	optional	BCC recipients
subject	string	optional	Email subject line — defaults to the template’s own subject when template_id is given
body_html	string	optional	HTML body. At least one of body_html/body_text/template_id must resolve to content
body_text	string	optional	Plain-text body (fallback)
template_id	integer	optional	Send using a saved template (see Templates below) instead of inline subject/body_html
variables	object	optional	{{placeholder}} substitutions applied to the template’s subject and body — ignored without template_id
reply_to	string	optional	Reply-To address
track_opens	boolean	optional	Embed a read-receipt tracking pixel — requires a plan with read-receipt support, silently ignored otherwise
scheduled_at	string	optional	ISO 8601 datetime (future, UTC) — queues instead of sending immediately
unsend_window	integer	optional	Seconds to hold before dispatch (max 30), for an "undo send" window
attachments	object[]	optional	Array of {filename, content_base64, content_type}. Total size capped by the sender’s plan
sandbox	boolean	optional	Runs the full pipeline (validation, quota checks skipped, tracking, webhooks) without an actual SMTP delivery — for integration testing. Doesn’t count against your daily/hourly quota, and is tagged "sandbox": true on any webhook events it triggers. Not supported together with scheduled_at.

Request — inline content

curl -X POST https://api.kerabie.email/mail/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "from_email": "hello@yourdomain.com",
        "to": ["user@example.com"],
        "subject": "Hello from the API",
        "body_html": "<p>This was sent via the Kerabie Mail API.</p>"
      }'

Request — using a saved template

{
  "from_email": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "template_id": 1,
  "variables": { "first_name": "Ada", "order_id": "12345" }
}

Response 200

{
  "message_id": "3fa31ded-d28f-4973-af7b-9ed56ef842d1",
  "status": "sent",
  "scheduled_at": null,
  "scheduled_id": null
}

status is "scheduled" instead of "sent" when scheduled_at or unsend_window is set — track or cancel it with the endpoints below, using the returned scheduled_id.

GEThttps://api.kerabie.email/mail/scheduled

List all emails scheduled for future delivery.

DELETEhttps://api.kerabie.email/mail/scheduled/{id}

Cancel a scheduled email before it is sent.

Templates

Reusable HTML emails with {{placeholder}} tags — build them visually under Templates in the sidebar (11 starter designs included, or start blank), then send with them via template_id on POST /mail/send above. Each template's ID is shown on its edit page and is copyable from the templates list.

GEThttps://api.kerabie.email/mail/templates

List your templates (paginated).

POSThttps://api.kerabie.email/mail/templates

Create a template.

Parameter	Type	Required	Description
name	string	required	Template name
subject	string	optional	Default subject — can contain {{placeholder}} tags
body_html	string	required	HTML body — can contain {{placeholder}} tags
is_shared	boolean	optional	Whether other users on a shared inbox can use this template

GEThttps://api.kerabie.email/mail/templates/{id}

Fetch a single template.

PATCHhttps://api.kerabie.email/mail/templates/{id}

Update a template's name, subject, body_html, or is_shared.

DELETEhttps://api.kerabie.email/mail/templates/{id}

Delete a template.

Inbox

GEThttps://api.kerabie.email/inbox

List messages in a mailbox folder.

Parameter	Type	Required	Description
email	string	required	Mailbox address
folder	string	optional	IMAP folder name (default: INBOX)
page	integer	optional	Page number (default: 1)
per_page	integer	optional	Items per page (default: 50, max: 100)
starred_only	boolean	optional	Return only starred messages
unseen_only	boolean	optional	Return only unread messages

Response 200

{
  "messages": [
    {
      "uid": 42,
      "subject": "Hello",
      "from": "sender@example.com",
      "date": "2026-05-17T09:30:00Z",
      "seen": false,
      "starred": false,
      "has_attachments": false,
      "size": 4200
    }
  ],
  "total": 87,
  "page": 1,
  "per_page": 50
}

GEThttps://api.kerabie.email/inbox/{uid}

Fetch a single message including full HTML/text body.

Parameter	Type	Required	Description
email	string	required	Mailbox address

PATCHhttps://api.kerabie.email/inbox/{uid}

Mark a message as read/unread or starred/unstarred, or move it to a folder.

Parameter	Type	Required	Description
email	string	required	Mailbox address
seen	boolean	optional	Mark read (true) or unread (false)
starred	boolean	optional	Star or unstar the message
folder	string	optional	Move to this IMAP folder (e.g. Archive, Trash)

DELETEhttps://api.kerabie.email/inbox/{uid}

Permanently delete a message.

Parameter	Type	Required	Description
email	string	required	Mailbox address

GEThttps://api.kerabie.email/inbox/folders

List all IMAP folders for a mailbox.

Parameter	Type	Required	Description
email	string	required	Mailbox address

Contacts

Contacts require a Pro or Premium plan.

GEThttps://api.kerabie.email/contacts

List contacts, optionally filtering by search term.

Parameter	Type	Required	Description
search	string	optional	Filter by name, email, or company

POSThttps://api.kerabie.email/contacts

Create a new contact.

Parameter	Type	Required	Description
name	string	required	Contact full name
email	string	required	Email address
phone	string	optional	Phone number
company	string	optional	Company name

PATCHhttps://api.kerabie.email/contacts/{id}

Update an existing contact. All fields optional.

DELETEhttps://api.kerabie.email/contacts/{id}

Delete a contact permanently.

Calendar

Calendar requires a Pro or Premium plan.

GEThttps://api.kerabie.email/calendar

List calendar events in a date range.

Parameter	Type	Required	Description
from	string	optional	ISO 8601 start date
to	string	optional	ISO 8601 end date

POSThttps://api.kerabie.email/calendar

Create a calendar event.

Parameter	Type	Required	Description
title	string	required	Event title
start	string	required	ISO 8601 start datetime
end	string	required	ISO 8601 end datetime
all_day	boolean	optional	All-day event (default: false)
description	string	optional	Event notes
location	string	optional	Physical or virtual location
color	string	optional	Hex color code for display
attendees	string[]	optional	Attendee email addresses

PATCHhttps://api.kerabie.email/calendar/{id}

Update an event. All fields optional.

DELETEhttps://api.kerabie.email/calendar/{id}

Delete an event permanently.

Labels

GEThttps://api.kerabie.email/labels

List all labels for the authenticated account.

POSThttps://api.kerabie.email/labels

Create a label.

Parameter	Type	Required	Description
name	string	required	Label name
color	string	required	Hex color (e.g. #416758)

DELETEhttps://api.kerabie.email/labels/{id}

Delete a label and remove it from all messages.

Usage

GEThttps://api.kerabie.email/mail/mailbox-usage

Get per-mailbox usage statistics — storage, emails today, AI requests today.

Parameter	Type	Required	Description
email	string	required	Mailbox address

{
  "email": "you@example.com",
  "plan": "Pro",
  "storage": { "used_mb": 234.5, "limit_mb": 10240, "percentage": 2.3 },
  "emails_today": { "sent": 12, "limit": 500, "percentage": 2.4 },
  "ai_today": { "used": 5, "limit": 50, "unlimited": false, "percentage": 10.0 }
}