Cakemail API
Cakemail API
The Cakemail API is a RESTful API that provides programmatic access to Cakemail's email marketing and transactional email platform.
Authentication
The API supports two authentication mechanisms. Choose the one that matches your use case:
Standard Tokens (JWT)
Short-lived JSON Web Tokens obtained via POST /token using the OAuth 2.0 Resource Owner Password Credentials grant. The response includes an access token (valid for a limited period) and a refresh token used to obtain a new access token when the current one expires. Use standard tokens for interactive sessions and first-party UI integrations where a human user logs in and the token lifetime matches the session.
Personal Access Tokens (PATs)
Long-lived, scoped bearer tokens prefixed with ck_pat_, created via POST /users/self/pats. PATs are tied to a specific user, carry an explicit scope list, and can optionally be restricted to a subset of account IDs. Use PATs for programmatic, automated, or agentic integrations — scripts, CI pipelines, third-party tools, and AI agents — where storing a username/password is undesirable and the principle of least privilege matters. PATs can be revoked individually without affecting the user's ability to log in.
Both token types are passed as Authorization: Bearer <token> on every request.
Core Concepts
- Accounts & Users: An account represents an organization. Each account has one or more users. Partner accounts can manage sub-accounts.
- Lists & Contacts: Lists are collections of contacts (email subscribers). Contacts belong to lists and can have custom attributes, tags, and interests.
- Campaigns: Email campaigns are created from templates, targeted to lists or segments, and scheduled for delivery.
- Transactional Email: The Email API allows sending individual transactional emails (receipts, notifications, password resets) with full tracking.
- Templates: Reusable email designs that can be shared across campaigns and transactional emails.
- Webhooks: Receive real-time notifications for events like bounces, opens, clicks, and unsubscribes.
Rate Limiting
API requests are rate-limited per account. When a rate limit is exceeded, the response body includes a detail array with limits containing limit, window, and retry_in fields.
Tags
Token
Standard token management (OAuth 2.0). Use these endpoints to obtain short-lived JWT access and refresh tokens via the Resource Owner Password Credentials grant, refresh expired tokens, and complete multi-factor authentication challenges. These tokens are intended for interactive sessions and first-party UI use. For programmatic or agentic integrations, see Personal Access Tokens.
Personal Access Tokens
Personal Access Token (PAT) management. PATs are long-lived, scoped bearer tokens (format:
ck_pat_<40 hex chars>) intended for programmatic integrations, automation scripts, CI pipelines, and agentic workflows. Unlike standard JWTs they carry an explicit scope list and can optionally be restricted to a subset of account IDs (allowed_account_ids), enabling the principle of least privilege. Lifecycle: create a PAT via POST /users/self/pats — the full token is returned once and must be stored securely. Use it as Authorization: Bearer ck_pat_... on any supported endpoint. Revoke it via DELETE /users/self/pats/{id} when it is no longer needed. Security best practices: request only the scopes your integration actually needs; set an expires_at for tokens used in ephemeral environments; store the plaintext token in a secret manager, not in source code; rotate PATs periodically and revoke any that may have been exposed.Account
Manage the authenticated user's own account. An account represents an organization on the platform with its own contacts, campaigns, and settings. Use these endpoints to view or update account details, address, and domains. To manage sub-accounts under a partner account, see the Sub-Account endpoints.
User
Manage users within an account. Users are individuals who can log in and perform actions. Each account can have multiple users with different roles. Includes user creation with email verification, password management, suspension, and multi-factor authentication (MFA) setup.
List
Manage contact lists. A list is a collection of contacts (email subscribers) with its own sender identity, language, and subscription settings. Lists support double opt-in, custom redirect URLs after subscription events, and webhook notifications. Also includes deprecated subscription form endpoints for legacy integrations — use the Form endpoints instead.
Contact
Manage contacts within lists. Contacts are individual email subscribers with an email address, subscription status, custom attributes, tags, and interests. Supports creating, importing, updating, unsubscribing, and deleting contacts. Bulk operations are available for tagging and interest management. Contact data can be exported to CSV files.
Segment
Create and manage segments within lists. A segment is a dynamic filter that defines a subset of contacts based on query criteria. Segments can be defined using SQL-like expressions, FIQL, or JSON query format. Segments are used to target specific audiences when sending campaigns.
Campaign
Create and manage email campaigns. A campaign combines content (from a template or custom HTML), an audience (a list or segment), and a sender identity. Campaigns go through a lifecycle: incomplete → scheduled → delivering → delivered. They can also be active (ready to schedule), suspended, resumed, canceled, archived, or deleted. Send test emails before scheduling to preview the final result.
Campaign Blueprint
Browse pre-built campaign blueprints. Blueprints are ready-made campaign designs that can be used as starting points for new campaigns.
Template
Create and manage reusable email templates. Templates contain the HTML/text content and subject line that can be reused across multiple campaigns. Templates support custom attributes, tags, and can be rendered to preview the final output.
Transactional Email
Send transactional emails using templates. Transactional emails are one-to-one messages triggered by user actions (order confirmations, password resets, notifications). Create reusable templates with merge tags, then send them to individual contacts. Includes deprecated template-based endpoints — for new integrations, use the Email API.
Email API
Submit and track individual transactional emails. The Email API provides full control over email content, tracking, and delivery. Each email goes through a lifecycle: submitted, queued, delivered, with events for opens, clicks, bounces, and unsubscribes. Includes statistics, activity logs, and tag-based organization.
Sender
Manage sender identities (name and email pairs) used as the 'From' address in campaigns and transactional emails. New senders require email confirmation before use.
DKIM
Manage DKIM (DomainKeys Identified Mail) keys for email authentication. DKIM signing improves deliverability and prevents email spoofing.
Domain
Configure custom tracking and bounce domains. Custom domains replace default platform URLs in email links and bounce handling with your own branded domains.
Suppressed Email
Manage the account-level email suppression list. Suppressed emails are blocked from receiving any messages. Includes export functionality for bulk data extraction.
Form
Create and manage hosted forms for collecting subscriber data. Forms can include reCAPTCHA verification, custom redirect URLs, and double opt-in. Forms are published to generate a public submission URL.
Webhook
Configure webhooks to receive real-time HTTP notifications when email events occur (delivery, open, click, bounce, unsubscribe, spam complaint). Webhooks can be filtered by event type and archived when no longer needed.
Interest
Manage interests (preference categories) that can be assigned to contacts. Interests enable preference-based segmentation and can be used in preference centers.
Custom Attribute
Define custom data fields for contacts. Custom attributes extend the contact model with account-specific fields (e.g. company name, purchase date) that can be used in segmentation and merge tags.
Tags
Manage contact tags for flexible organization and segmentation. Tags are simple labels that can be attached to contacts for grouping and filtering.
Report
Access campaign, list, and account performance statistics. Includes open rates, click rates, bounce rates, and other delivery metrics. Campaign report data can be exported to CSV files.
Log
Access detailed activity logs for campaigns and lists. Logs track individual email events (sends, opens, clicks, bounces, unsubscribes). Log data can be exported to CSV files.
Links
Retrieve link information from campaigns, including tracked URLs.
System Email
Configure system-generated emails such as double opt-in confirmations, welcome messages, and unsubscribe confirmations. System emails can be customized per language.
Task
Monitor asynchronous background tasks such as exports and imports. Tasks track the progress and status of long-running operations.
Logo
Upload and manage the account logo used in campaigns and forms.
Sub-Account
Manage sub-accounts under a partner or organization account. Sub-accounts are independent accounts with their own users, contacts, and campaigns, managed by the parent account. Includes creation, suspension, and configuration.
Action
Workflow
Workflow Blueprint