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

```shell
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.

```shell
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](/docs/senders/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.

```shell
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.

```shell
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

```json
{
  "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.

```shell
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

- [Getting Started with Email API](/guides/getting-started-email-api) - Overview and choosing integration method
- [Sending Emails via SMTP](/guides/sending-emails-smtp) - Alternative SMTP integration
- [Email API Reference](/guides/email-api-reference) - Quick reference guide
- [Authenticating Domains](/docs/senders/authenticating-domains) - SPF/DKIM setup
- [Managing Contact Lists](/docs/audience/managing-contact-lists) - Contact management