Email API

Email API reference

Copy page

Quick reference guide for Cakemail Email API. Use this page to quickly look up endpoints, headers, and configuration options for both REST and SMTP integration methods.

REST API Endpoints

Authentication

POST /token

Obtain an access token for API authentication.

Parameters:

• grant_type: password
• username: Your Cakemail username
• password: Your Cakemail password

Returns: Access token for use in Authorization header

---

Senders

POST /brands/default/senders

Create and register a new sender email address.

Headers:

• Authorization: Bearer YOUR_ACCESS_TOKEN
• Content-Type: application/json

Body:

Code
 
{
  "name": "Sender Name",
  "email": "sender@example.com"
}

Note: Auto-confirmed if email matches account email, otherwise requires email verification.

---

Lists

GET /lists

Retrieve your contact lists and their IDs.

Headers:

• Authorization: Bearer YOUR_ACCESS_TOKEN

Returns: Array of lists with IDs

---

Send Email

POST /v2/emails

Send an email through the Email API.

Headers:

• Authorization: Bearer YOUR_ACCESS_TOKEN
• Content-Type: application/json

Required Fields:

• list_id: Contact list ID
• sender.id: Verified sender ID
• email: Recipient email address
• content.type: marketing or transactional
• content.subject: Email subject
• content.html: Email body HTML

Optional Fields:

• content.encoding: Character encoding (default: utf-8)
• tags: Array of tags

---

Check Status

GET /v2/emails/:email-id

Check the delivery status of a sent email.

Headers:

• Authorization: Bearer YOUR_ACCESS_TOKEN

Returns: Email status and details

---

SMTP Configuration

Server Settings

Setting	Value
Host	smtp.cakemail.dev
Port	465
Encryption	SSL/TLS (SMTPS)
Authentication	Username and password required

Authentication

Use your Cakemail account credentials:

• Username: Your Cakemail username
• Password: Your Cakemail password

---

SMTP Headers

Required Headers

Header	Format	Purpose
From	sender@example.com	Sender email (must be validated)
To	recipient@example.com	Recipient email (single recipient only)
Subject	Your subject here	Email subject line
x-email-api-enabled	true	Enables Email API routing
x-list-id	9234980	Associates email with contact list

Optional Headers

Header	Format	Default	Purpose
x-email-api-type	marketing or transactional	marketing	Email type classification
x-tags	tag1,tag2	None	Comma-separated tags

---

Email Types

Marketing

When to use:

• Newsletters and promotional campaigns
• Product announcements
• Marketing content and offers

Characteristics:

• Subject to marketing consent requirements
• May be filtered by email clients
• Bulk sending optimized

Transactional

When to use:

• Order confirmations and receipts
• Password resets and account notifications
• User-triggered system emails
• Time-sensitive communications

Characteristics:

• Higher priority delivery
• Less likely to be filtered
• Must be directly related to user actions

---

Best Practices

Sender Authentication

Always authenticate your domain with SPF and DKIM records before sending emails:

• Register your sender email in Cakemail
• Complete email verification process
• Add SPF and DKIM records to your DNS
• Monitor sender reputation

Learn more about authentication

List Management

Use lists for proper contact management and compliance:

• Required for bounce handling
• Maintains consent records
• Enables automatic unsubscribe processing
• Tracks contact engagement

Learn more about contact lists

Error Handling

Implement robust error handling in your integration:

• Catch authentication failures and refresh tokens
• Handle invalid sender or list ID errors
• Monitor delivery status for critical emails
• Log errors for troubleshooting

SMTP Limitations

Be aware of SMTP-specific constraints:

• Single recipient only: Make separate calls for multiple recipients
• Attachments disabled by default: Contact support to enable
• Headers required: Always include x-email-api-enabled and x-list-id

---

Response Formats

Successful Email Submission

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

The data.id field contains the email ID for status tracking.

---

Support Resources

• Documentation: https://docs.cakemail.com/en/api/email-api
• Product Page: https://www.cakemail.com/solutions/email-api
• Email Support: support@cakemail.com
• Status Page: https://status.cakemail.com/

---

Related Guides

• Getting Started with Email API - Overview and choosing integration method
• Sending Emails via REST API - Complete REST API guide
• Sending Emails via SMTP - Complete SMTP guide
• Authenticating Domains - SPF/DKIM setup