# Email API reference

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:**
```json
{
  "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` or `587` |
| **Encryption** | SSL/TLS (SMTPS) on port 465; STARTTLS on port 587 |
| **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](/docs/senders/authenticating-domains)

### 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](/docs/audience/managing-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

```json
{
  "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](https://docs.cakemail.com/en/api/email-api)
- **Product Page**: [https://www.cakemail.com/solutions/email-api](https://www.cakemail.com/solutions/email-api)
- **Email Support**: [support@cakemail.com](mailto:support@cakemail.com)
- **Status Page**: [https://status.cakemail.com/](https://status.cakemail.com/)

---

## Related Guides

- [Getting Started with Email API](/guides/getting-started-email-api) - Overview and choosing integration method
- [Sending Emails via REST API](/guides/sending-emails-rest-api) - Complete REST API guide
- [Sending Emails via SMTP](/guides/sending-emails-smtp) - Complete SMTP guide
- [Authenticating Domains](/docs/senders/authenticating-domains) - SPF/DKIM setup