REST API

Endpoint and authentication

Send requests to your explicit Runtime URL. CFsend does not provide a shared sending endpoint.

POST $ALL2CF_SEND_URL/emails
Authorization: Bearer $ALL2CF_SEND_KEY

Create separate keys by Runtime, environment and permission. Store the URL and key in application secrets.

Send an email

curl "$ALL2CF_SEND_URL/emails" \
  -H "Authorization: Bearer $ALL2CF_SEND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1048" \
  -d '{"from":"hello@example.com","to":"customer@example.net","subject":"Your receipt","html":"<h1>Paid</h1>"}'

Stable resources

• POST /emails and /emails/batch
• GET /emails and /emails/:id
• Templates, domains and API keys
• Webhooks, logs, suppressions and topics
• Idempotent scheduling and cancellation

Treat 4xx responses as request, credential or policy failures. Retry eligible 429 and 5xx responses with backoff and the same idempotency key.

Request fields

from, to, subject, text and html form the message. Optional fields include cc, bcc, reply_to, template, attachments, headers, tags, metadata, scheduled_at, stream_id, message_class, subscription_topic_id and a deliverability policy. Provide text or HTML unless a template supplies content.

GET /emails?limit=50&after=... lists messages. GET /emails/:id reads one; PATCH /emails/:id changes a future scheduled_at; POST /emails/:id/cancel cancels before dispatch. Batch accepts up to 100 messages through the SDK/MCP contract and supports strict or permissive validation.

Errors and retries

The JSON error has a stable name and human-readable message. 401 is credential failure, 403 permission/policy, 409 conflicting idempotency, 413 size, 422 a semantic precondition, 429 rate/quota, and 5xx a Runtime/provider failure. Record the message ID and error name. Never generate a new idempotency key merely because the client timed out.