Cakemail
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:

TerminalCode
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.

TerminalCode
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.

TerminalCode
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.

TerminalCode
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

JSONCode
{
  "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.

TerminalCode
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

Related Documentation

Last modified on
Getting started with Email APIEmail configuration