API Reference — Cascade Mail

Authentication

All API requests require authentication via an API key passed as a Bearer token in the Authorization header. All requests must be made over HTTPS.

Authorization: Bearer cm_live_your_api_key_here

Base URL: All endpoints are relative to https://api.cascade-mail.net/v1. Responses are returned in JSON format. Requests must include Content-Type: application/json for POST/PUT/PATCH bodies.

Messages

POST /v1/messages

Send a single email message. Returns a message ID for tracking.

Parameter	Type	Description
`from` required	object	Sender `email` and `name`. Domain must be verified.
`to` required	array	Array of recipient objects with `email` and optional `name`. Max 50 per request.
`subject` required	string	Email subject line.
`html`	string	HTML body content. At least one of `html` or `text` required.
`text`	string	Plain text body content.
`template_id`	string	Use a saved template instead of inline content.
`variables`	object	Key-value pairs for template variable substitution.
`tags`	array	String tags for categorization and filtering. Max 5 tags.
`headers`	object	Custom email headers (e.g., `Reply-To`, `X-Custom-ID`).
`track_opens`	boolean	Enable open tracking. Default: `true`.
`track_clicks`	boolean	Enable click tracking. Default: `true`.
`attachments`	array	Array of objects with `filename`, `content` (base64), and `content_type`.

POST /v1/messages/batch

Send up to 500 messages in a single API call. Accepts an array of message objects with the same schema as the single send endpoint. Returns an array of message IDs.

GET /v1/messages/{message_id}

Retrieve the status and delivery details of a sent message.

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "delivered",
  "from": { "email": "orders@yourdomain.com" },
  "to": "customer@example.com",
  "subject": "Your order has shipped",
  "created_at": "2026-02-17T14:30:00Z",
  "delivered_at": "2026-02-17T14:30:03Z",
  "opens": 2,
  "clicks": 1,
  "tags": ["transactional", "shipping"]
}

Lists

GET /v1/lists

Retrieve all subscriber lists. Supports pagination with page and per_page query parameters.

POST /v1/lists

Create a new subscriber list.

Parameter	Type	Description
`name` required	string	Display name for the list.
`description`	string	Optional description.
`double_optin`	boolean	Require email confirmation for new subscribers. Default: `false`.

GET /v1/lists/{list_id}

Retrieve details and stats for a specific list.

PATCH /v1/lists/{list_id}

Update list name, description, or settings.

DELETE /v1/lists/{list_id}

Delete a list and optionally remove all associated subscribers.

Subscribers

GET /v1/lists/{list_id}/subscribers

Retrieve subscribers in a list. Supports filtering by status (active, unsubscribed, bounced) and pagination.

POST /v1/lists/{list_id}/subscribers

Add a subscriber to a list.

Parameter	Type	Description
`email` required	string	Subscriber email address.
`name`	string	Display name.
`fields`	object	Custom field key-value pairs.
`consent`	object	Consent record: `type` (express/implied), `source`, `timestamp`.

POST /v1/lists/{list_id}/subscribers/import

Bulk import subscribers via CSV upload or JSON array. Max 50,000 subscribers per import. Returns a job ID for tracking import progress.

PATCH /v1/lists/{list_id}/subscribers/{subscriber_id}

Update subscriber fields, name, or consent records.

DELETE /v1/lists/{list_id}/subscribers/{subscriber_id}

Remove a subscriber from a list.

Campaigns

GET /v1/campaigns

Retrieve all campaigns. Filter by status (draft, scheduled, sending, sent).

POST /v1/campaigns

Create a new email campaign.

Parameter	Type	Description
`name` required	string	Internal campaign name.
`subject` required	string	Email subject line.
`from` required	object	Sender `email` and `name`.
`list_id` required	string	Target subscriber list.
`html`	string	HTML content (or use `template_id`).
`template_id`	string	Saved template to use.
`segment_id`	string	Optional segment filter within the list.
`scheduled_at`	datetime	ISO 8601 datetime to schedule sending. Omit to save as draft.

POST /v1/campaigns/{campaign_id}/send

Immediately send a draft campaign. Cannot be undone once sending begins.

GET /v1/campaigns/{campaign_id}

Retrieve campaign details and real-time delivery statistics.

Templates

GET /v1/templates

List all saved templates.

POST /v1/templates

Create a new template.

Parameter	Type	Description
`name` required	string	Template name for reference.
`subject`	string	Default subject line (can be overridden at send time).
`html` required	string	HTML content with `{{variable}}` placeholders.
`text`	string	Plain text version.

PATCH /v1/templates/{template_id}

Update an existing template.

DELETE /v1/templates/{template_id}

Delete a template.

Domains

GET /v1/domains

List all registered sending domains and their verification status.

POST /v1/domains

Parameter	Type	Description
`domain` required	string	The domain name (e.g., `yourdomain.com`).

POST /v1/domains/{domain_id}/verify

Trigger DNS verification check. Returns current verification status for SPF, DKIM, and DMARC records.

DELETE /v1/domains/{domain_id}

Remove a sending domain. Messages can no longer be sent from this domain.

Webhooks

GET /v1/webhooks

List all configured webhook endpoints.

POST /v1/webhooks

Create a new webhook endpoint.

Parameter	Type	Description
`url` required	string	HTTPS endpoint URL to receive events.
`events` required	array	Event types to subscribe to (e.g., `message.delivered`, `message.bounced`).
`active`	boolean	Enable or disable the webhook. Default: `true`.

PATCH /v1/webhooks/{webhook_id}

Update a webhook URL, subscribed events, or active status.

DELETE /v1/webhooks/{webhook_id}

Delete a webhook endpoint.

Analytics

GET /v1/analytics

Retrieve aggregate sending analytics for your account.

Parameter	Type	Description
`from` required	date	Start date (YYYY-MM-DD).
`to` required	date	End date (YYYY-MM-DD).
`tag`	string	Filter by message tag.
`domain`	string	Filter by sending domain.
`group_by`	string	Group results by `day`, `week`, or `month`.

GET /v1/analytics/campaigns/{campaign_id}

Retrieve detailed analytics for a specific campaign, including per-link click data and engagement timeline.

Suppressions

GET /v1/suppressions

List all suppressed email addresses. Filter by reason (unsubscribe, bounce, complaint, manual).

POST /v1/suppressions

Manually add an address to the suppression list.

Parameter	Type	Description
`email` required	string	Email address to suppress.
`reason`	string	Reason for suppression. Default: `manual`.

DELETE /v1/suppressions/{email}

Remove an address from the suppression list. Use with caution — re-enabling a previously bounced or complained address can impact sender reputation.

Events

GET /v1/events

Retrieve a chronological log of email events. Use this endpoint to poll for delivery status if you are not using webhooks.

Parameter	Type	Description
`from`	datetime	Start of time range (ISO 8601).
`to`	datetime	End of time range (ISO 8601).
`event`	string	Filter by event type.
`message_id`	string	Filter by specific message.
`recipient`	string	Filter by recipient email.
`tag`	string	Filter by tag.
`per_page`	integer	Results per page (max 100, default 50).
`cursor`	string	Pagination cursor from previous response.