Email API

Sending emails via REST API

Send emails through Cakemail's /v2/emails API endpoint using standard HTTP requests. This guide walks you through the essential steps to send your first email using the REST API.

Overview

The Cakemail REST API provides direct HTTP access to email sending functionality. Use this method when you need programmatic control, detailed status tracking, or want to integrate with modern web applications and microservices.

Authentication

To interact with the Cakemail API, you'll need an access token. This token authenticates your requests.

Obtain Your Access Token

Make a POST request to the /token endpoint with your Cakemail username and password:

Code
 
curl --request POST \
  --url https://api.cakemail.dev/token \
  --data-urlencode grant_type=password \
  --data-urlencode username=YOUR_USERNAME \
  --data-urlencode password=YOUR_PASSWORD

A successful response will provide an access token, which you'll use in subsequent API calls.

Key Notes:

Cakemail API tokens are private and must be securely stored, only accessible to your backend application.
Include the token in the Authorization: Bearer YOUR_ACCESS_TOKEN header for all API requests.

Prerequisites

Before sending emails, you need to set up a sender and identify your contact list.

Create a Sender

A confirmed sender is required to send emails with the Email API.

Code
 
curl --request POST \
  --url https://api.cakemail.dev/brands/default/senders \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"Sender Name","email":"sender@example.com"}'

Key Notes:

If the sender email matches your account's email, it will be auto-confirmed.
Otherwise, a confirmation email will be sent, and the recipient must click the activation link.
The sender email must be authenticated with SPF/DKIM records. Learn more: Authenticating Domains
Your tracking domain must be branded on your proper domain

Find Your List ID

Contact management is provided by the Cakemail Contact List feature. A List ID must be used to send email with the Email API.

Code
 
curl --request GET \
  --url https://api.cakemail.dev/lists \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json'

The response will include your available lists with their IDs. Use the id field from your chosen list when sending emails.

Sending Your First Email

Now that you have a confirmed sender and list ID, you can submit an email using the /v2/emails endpoint.

Code
 
curl --request POST \
  --url https://api.cakemail.dev/v2/emails \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "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

list_id: The ID of your contact list
sender.id: The ID of your verified sender
email: The recipient's email address
content.type: Email type (marketing or transactional)
content.subject: Email subject line
content.html: Email body content in HTML format

Optional Fields

content.encoding: Character encoding (default: utf-8)
tags: Array of tags for organizing and filtering emails

Example Response


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

The response includes an email ID that you can use to check the delivery status.

Checking Email Status

You can follow the email status using the /v2/emails/:email-id endpoint.

Code
 
curl --request GET \
  --url https://api.cakemail.dev/v2/emails/EMAIL_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

This optional step allows you to monitor delivery progress and troubleshoot any issues.

Troubleshooting

Authentication Errors

Problem: Invalid credentials or token expired

Solutions:

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

Invalid Sender Errors

Problem: Sender not validated or not found

Solutions:

Confirm the sender email is registered in your Cakemail account
Check that the sender has completed email verification
Verify the sender ID matches an existing sender
Ensure your domain is authenticated with SPF/DKIM records

List ID Not Found

Problem: The specified list ID doesn't exist

Solutions:

Use the GET /lists endpoint to retrieve your available lists
Verify the list_id value is correct and exists in your account
Ensure the list hasn't been deleted

Delivery Issues

Problem: Email sent but not received

Solutions:

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

Getting Started with Email API - Overview and choosing integration method
Sending Emails via SMTP - Alternative SMTP integration
Email API Reference - Quick reference guide
Authenticating Domains - SPF/DKIM setup
Managing Contact Lists - Contact management

Last modified on September 29, 2026

Getting started with Email API Email configuration

Email API

Sending emails via REST API

Send emails through Cakemail's /v2/emails API endpoint using standard HTTP requests. This guide walks you through the essential steps to send your first email using the REST API.

Overview

Authentication

To interact with the Cakemail API, you'll need an access token. This token authenticates your requests.

Obtain Your Access Token

Make a POST request to the /token endpoint with your Cakemail username and password:

Code
 
curl --request POST \
  --url https://api.cakemail.dev/token \
  --data-urlencode grant_type=password \
  --data-urlencode username=YOUR_USERNAME \
  --data-urlencode password=YOUR_PASSWORD

A successful response will provide an access token, which you'll use in subsequent API calls.

Key Notes:

Cakemail API tokens are private and must be securely stored, only accessible to your backend application.
Include the token in the Authorization: Bearer YOUR_ACCESS_TOKEN header for all API requests.

Prerequisites

Before sending emails, you need to set up a sender and identify your contact list.

Create a Sender

A confirmed sender is required to send emails with the Email API.

Code
 
curl --request POST \
  --url https://api.cakemail.dev/brands/default/senders \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"Sender Name","email":"sender@example.com"}'

Key Notes:

If the sender email matches your account's email, it will be auto-confirmed.
Otherwise, a confirmation email will be sent, and the recipient must click the activation link.
The sender email must be authenticated with SPF/DKIM records. Learn more: Authenticating Domains
Your tracking domain must be branded on your proper domain

Find Your List ID

Contact management is provided by the Cakemail Contact List feature. A List ID must be used to send email with the Email API.

Code
 
curl --request GET \
  --url https://api.cakemail.dev/lists \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json'

The response will include your available lists with their IDs. Use the id field from your chosen list when sending emails.

Sending Your First Email

Now that you have a confirmed sender and list ID, you can submit an email using the /v2/emails endpoint.

Code
 
curl --request POST \
  --url https://api.cakemail.dev/v2/emails \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "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

list_id: The ID of your contact list
sender.id: The ID of your verified sender
email: The recipient's email address
content.type: Email type (marketing or transactional)
content.subject: Email subject line
content.html: Email body content in HTML format

Optional Fields

content.encoding: Character encoding (default: utf-8)
tags: Array of tags for organizing and filtering emails

Example Response


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

The response includes an email ID that you can use to check the delivery status.

Checking Email Status

You can follow the email status using the /v2/emails/:email-id endpoint.

Code
 
curl --request GET \
  --url https://api.cakemail.dev/v2/emails/EMAIL_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

This optional step allows you to monitor delivery progress and troubleshoot any issues.

Troubleshooting

Authentication Errors

Problem: Invalid credentials or token expired

Solutions:

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

Invalid Sender Errors

Problem: Sender not validated or not found

Solutions:

Confirm the sender email is registered in your Cakemail account
Check that the sender has completed email verification
Verify the sender ID matches an existing sender
Ensure your domain is authenticated with SPF/DKIM records

List ID Not Found

Problem: The specified list ID doesn't exist

Solutions:

Use the GET /lists endpoint to retrieve your available lists
Verify the list_id value is correct and exists in your account
Ensure the list hasn't been deleted

Delivery Issues

Problem: Email sent but not received

Solutions:

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

Getting Started with Email API - Overview and choosing integration method
Sending Emails via SMTP - Alternative SMTP integration
Email API Reference - Quick reference guide
Authenticating Domains - SPF/DKIM setup
Managing Contact Lists - Contact management

Last modified on September 29, 2026

Getting started with Email API Email configuration

Overview

Authentication

Obtain Your Access Token

Prerequisites

Create a Sender

Find Your List ID

Sending Your First Email

Required Fields

Optional Fields

Example Response

Checking Email Status

Troubleshooting

Authentication Errors

Invalid Sender Errors

List ID Not Found

Delivery Issues

Related Documentation

Overview

Authentication

Obtain Your Access Token

Prerequisites

Create a Sender

Find Your List ID

Sending Your First Email

Required Fields

Optional Fields

Example Response

Checking Email Status

Troubleshooting

Authentication Errors

Invalid Sender Errors

List ID Not Found

Delivery Issues

Related Documentation