Sending Emails via REST API | Cakemail Documentation

Send emails through Cakemail's /v2/emails endpoint using standard HTTP requests. This guide walks you through authentication, sender setup, sending your first email, and troubleshooting.

Authentication

Obtain an access token by calling the /token endpoint:

curl -X POST https://api.cakemail.dev/token \
  -d "grant_type=password" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD"

Use the token in subsequent requests via the Authorization: Bearer YOUR_ACCESS_TOKEN header.

API tokens are private. Store them securely and only use them from your backend.

Prerequisites

Create a sender

A confirmed sender is required before sending:

curl -X POST https://api.cakemail.dev/brands/default/senders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sender Name", "email": "sender@example.com"}'

If the sender email matches your account email, it's auto-confirmed
Otherwise, a confirmation email is sent — the recipient must click the activation link
The sender domain must be authenticated with SPF/DKIM records
Your tracking domain must be branded on your domain

Find your list ID

Contact management is required for compliance and bounce handling:

curl https://api.cakemail.dev/lists \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use the id field from your chosen list when sending emails.

Send an email

curl -X POST https://api.cakemail.dev/v2/emails \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": LIST_ID,
    "sender": { "id": SENDER_ID },
    "email": "recipient@example.com",
    "content": {
      "type": "marketing",
      "subject": "Hello, world!",
      "html": "<html><body>Hello, world!</body></html>",
      "encoding": "utf-8"
    }
  }'

Required fields

Field	Description
`list_id`	Contact list ID
`sender.id`	Verified sender ID
`email`	Recipient email address
`content.type`	`marketing` or `transactional`
`content.subject`	Email subject line
`content.html`	HTML body content

Optional fields

Field	Description
`content.encoding`	Character encoding (default: `utf-8`)
`tags`	Array of tags for filtering

Response

{
  "email": "recipient@example.com",
  "object": "email",
  "submitted": true,
  "data": {
    "id": "3fbfa67e-c4c4-4e03-8dfd-556037960374",
    "status": "queued"
  }
}

Check email status

Track delivery progress using the email ID from the send response:

curl https://api.cakemail.dev/v2/emails/EMAIL_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Email lifecycle

Each email moves through a series of statuses:

Status	Meaning
`submitted`	Email accepted by the API
`queued`	Email queued for delivery
`delivered`	Successfully delivered to the recipient's mail server
`opened`	Recipient opened the email
`clicked`	Recipient clicked a link
`bounced`	Delivery failed
`complained`	Recipient marked as spam

Activity logs and tags

Tag emails for organized tracking:

curl -X POST https://api.cakemail.dev/v2/emails \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "tags": ["password-reset", "auth"],
    "list_id": LIST_ID,
    "sender": { "id": SENDER_ID },
    "content": {
      "type": "transactional",
      "subject": "Password Reset",
      "html": "<p>Click to reset.</p>"
    }
  }'

Filter activity logs by tag, date, or status:

curl "https://api.cakemail.dev/v2/logs/emails?tags=password-reset&page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Troubleshooting

Authentication errors

Verify your username and password
Ensure your account has API access enabled
Obtain a new token if the current one has expired

Invalid sender

Confirm the sender email is registered and verified
Verify the sender ID exists
Ensure the domain is authenticated with SPF/DKIM

List ID not found

Use GET /lists to retrieve available lists
Verify the list hasn't been deleted

Email not received

Check spam/junk folders
Verify the recipient email address is valid
Review your sender reputation and authentication
Monitor bounce reports in your Cakemail account