Documentation

Getting Started

Welcome to the Cascade Mail documentation. This guide covers everything you need to start sending transactional and marketing email through the Cascade Mail platform.

Sending Email via API

The Cascade Mail API accepts JSON payloads over HTTPS. All API requests require authentication via your API key passed in the Authorization header.

Basic Send Request

POST /v1/messages
Host: api.cascade-mail.net
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "from": {
    "email": "orders@yourdomain.com",
    "name": "Your Company"
  },
  "to": [
    { "email": "customer@example.com", "name": "Jane Doe" }
  ],
  "subject": "Your order has shipped",
  "html": "<h1>Order Shipped</h1><p>Your package is on the way.</p>",
  "text": "Your package is on the way.",
  "tags": ["transactional", "shipping"]
}

Response

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "queued",
  "created_at": "2026-02-17T14:30:00Z"
}

Messages are queued for immediate delivery. Use the returned id to track delivery status via the API or webhooks.

API Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme. API keys can be created and managed from your dashboard under Settings → API Keys.

Authorization: Bearer cm_live_abc123def456...

Cascade Mail provides two types of API keys:

• Live keys (cm_live_) — Used in production to send real email.
• Test keys (cm_test_) — Used in development. Messages are validated but not delivered.

Domain Setup & DNS

Before sending, you must verify ownership of your sending domain and configure email authentication records. Navigate to Settings → Sending Domains and add your domain. Cascade Mail will provide the DNS records you need to configure:

SPF Record

Add or update your domain's TXT record to include Cascade Mail's sending servers:

v=spf1 include:spf.cascade-mail.net ~all

DKIM Record

Add the provided CNAME record to publish your DKIM public key. Cascade Mail generates unique 2048-bit RSA key pairs for each domain:

cm._domainkey.yourdomain.com  CNAME  cm._domainkey.cascade-mail.net

DMARC Record

We recommend publishing a DMARC policy for your domain. At minimum, start with a monitoring policy:

_dmarc.yourdomain.com  TXT  "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com"

Once verified, your domain status will show as Active in the dashboard. DNS propagation typically completes within a few minutes but may take up to 48 hours.

SMTP Relay

If you prefer SMTP integration over the REST API, Cascade Mail provides a fully authenticated SMTP relay endpoint.

SMTP Settings

Host:     smtp.cascade-mail.net
Port:     587 (STARTTLS) or 465 (SSL/TLS)
Username: Your API key
Password: Your API key
Auth:     PLAIN or LOGIN

SMTP supports all the same features as the API, including tagging (via custom headers), templates, and tracking. Add the X-CM-Tag header to categorize messages sent via SMTP.

Webhooks

Cascade Mail can send real-time event notifications to your server via webhooks. Configure webhook endpoints in Settings → Webhooks.

Supported Events

• message.delivered — Message successfully delivered to the recipient's mail server.
• message.bounced — Message bounced (hard or soft). Includes bounce code and classification.
• message.opened — Recipient opened the message (tracking pixel loaded).
• message.clicked — Recipient clicked a tracked link in the message.
• message.complained — Recipient marked the message as spam via ISP feedback loop.
• message.unsubscribed — Recipient clicked the unsubscribe link or used List-Unsubscribe header.
• message.deferred — Delivery temporarily delayed; Cascade Mail will retry automatically.

Webhook Payload

{
  "event": "message.delivered",
  "timestamp": "2026-02-17T14:30:05Z",
  "message_id": "msg_a1b2c3d4e5f6",
  "recipient": "customer@example.com",
  "tags": ["transactional", "shipping"],
  "metadata": {
    "ip": "198.51.100.25",
    "response": "250 2.0.0 OK"
  }
}

Webhook requests include an X-CM-Signature header containing an HMAC-SHA256 signature for payload verification. Always validate signatures before processing webhook data.

Analytics & Reporting

The Cascade Mail dashboard provides real-time analytics for all your sending activity. Key metrics include delivery rate, bounce rate (hard and soft), open rate, click rate, unsubscribe rate, and complaint rate. All metrics can be filtered by date range, sending domain, tag, and campaign.

Analytics API

GET /v1/analytics?from=2026-02-01&to=2026-02-17&tag=shipping

{
  "sent": 15420,
  "delivered": 15105,
  "bounced": 315,
  "opened": 8230,
  "clicked": 2104,
  "unsubscribed": 12,
  "complained": 3
}

List Management

Cascade Mail provides tools to manage your subscriber lists directly through the dashboard or API. You can create and organize multiple lists, import subscribers via CSV upload or API, manage custom fields and segments, and track subscription status and engagement history.

Add a Subscriber

POST /v1/lists/{list_id}/subscribers
{
  "email": "subscriber@example.com",
  "name": "John Smith",
  "fields": {
    "company": "Acme Corp",
    "plan": "enterprise"
  },
  "consent": {
    "type": "express",
    "source": "signup_form",
    "timestamp": "2026-02-17T10:00:00Z"
  }
}

Templates

Create reusable email templates with dynamic content using Cascade Mail's template engine. Templates support variable substitution using double-brace syntax:

<h1>Hello, {{name}}</h1>
<p>Your order #{{order_id}} has been confirmed.</p>
<p>Estimated delivery: {{delivery_date}}</p>

Pass template variables in your API send request:

{
  "to": [{ "email": "customer@example.com" }],
  "template_id": "tpl_order_confirm",
  "variables": {
    "name": "Jane",
    "order_id": "ORD-78542",
    "delivery_date": "February 22, 2026"
  }
}

Rate Limits

API requests are rate-limited based on your account plan. Rate limit headers are included in every API response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1708185600

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your integration to handle rate limiting gracefully.

Error Handling

The API uses standard HTTP status codes and returns structured JSON error responses:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_recipient",
    "message": "The 'to' address is not a valid email address.",
    "field": "to[0].email"
  }
}

Common Error Codes

• 400 — Bad Request. Check the error.field for the specific invalid parameter.
• 401 — Unauthorized. Your API key is missing or invalid.
• 403 — Forbidden. Your API key lacks permission for this action.
• 404 — Not Found. The requested resource does not exist.
• 422 — Unprocessable Entity. The request is well-formed but contains semantic errors.
• 429 — Too Many Requests. You've exceeded the rate limit.
• 500 — Internal Server Error. Retry with exponential backoff.