> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Create and send email campaigns to your contact lists. Unsubscribes are handled for you.

**1. Create the campaign**

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/email/campaigns \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter",
    "subject": "What'\''s new in November",
    "htmlBody": "<h1>Hello!</h1><p>…</p>",
    "fromEmail": "news@yourbrand.co.ke",
    "fromName": "Your Brand",
    "contactListIds": ["c51e…"]
  }'
```

It's saved as a `draft`. `fromEmail` must be on a domain you've verified in the dashboard.

**2. Send it**

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/email/campaigns/e9a0…/send \
  -H "Authorization: Bearer $TELAVEN_API_KEY"
```

```json theme={null}
{
  "success": true,
  "message": "Campaign sent. 796 delivered, 0 failed.",
  "data": { "totalSent": 796, "totalFailed": 0, "status": "completed" }
}
```

## Campaign fields

**name** `string` *required*

For your reference.

**subject** `string` *required*

Subject line.

**htmlBody** `string` *required*

HTML content. Marketing emails get an unsubscribe footer added automatically.

**textBody** `string`

Plain-text version.

**fromEmail** `string`

A sender address on a verified domain.

**fromName** `string`

Sender name.

**replyTo** `string`

Reply-to address.

**contactListIds** `string[]`

Contact lists to send to.

**manualEmails** `string[]`

Extra addresses.

**campaignType** `string`

`marketing` (default) or `transactional`.

**sendType** `string`

`immediate` (default) or `scheduled`.

**scheduledAt** `string`

Required when `sendType` is `scheduled`.

## Unsubscribes

Unsubscribed addresses are skipped on every send.

| Call | Does |
| - | - |
| [`GET /email/unsubscribes`](https://docs.telaven.com/api-reference/email/list-unsubscribes) | Lists addresses that opted out. |
| [`POST /email/unsubscribes`](https://docs.telaven.com/api-reference/email/add-unsubscribe) | Stops marketing email to an address, for example when a customer asks by phone. |
| [`DELETE /email/unsubscribes?email=…`](https://docs.telaven.com/api-reference/email/re-subscribe-an-address) | Allows marketing email to an address again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.