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

# Newsletter campaigns

> Create and send email broadcasts to your subscriber list from the platform console.

Newsletter campaigns let platform administrators send email broadcasts to subscribers. Use them for product announcements, feature launches, compliance updates, or any communication that goes to your full subscriber base.

<Info>
  Newsletter campaigns are a platform administration feature, separate from the [AI CMO](/guides/ai-cmo) outbound engine. The AI CMO handles autonomous, personalized outreach to leads. Newsletter campaigns are manual, one-to-many broadcasts to subscribers.
</Info>

## Prerequisites

* Platform administrator access to the [console](https://console.truthlocks.com)

## How it works

1. **Build your subscriber list.** Subscribers are added through your website, API integrations, or other acquisition channels. Manage them from the console.
2. **Compose a campaign.** Write a subject line, preview text, and HTML email body. Preview the rendered email inline before sending.
3. **Test.** Send a test email to any address to verify formatting and content.
4. **Send.** Broadcast the campaign to all active subscribers. Delivery stats are tracked automatically.

## Subscribers

### Viewing subscribers

Open **Newsletter** in the platform console. The main page shows two sections:

* **Subscribers** — a searchable, paginated list of all subscribers with their email, name, status, source, and subscription date.
* **Campaigns** — a list of all newsletter campaigns with their status and delivery stats.

### Subscriber statuses

| Status         | Description                                  |
| :------------- | :------------------------------------------- |
| `ACTIVE`       | Subscribed and eligible to receive campaigns |
| `UNSUBSCRIBED` | Opted out of communications                  |
| `BOUNCED`      | Email delivery failed permanently            |

### Removing a subscriber

Click the delete icon next to any subscriber to remove them from the list. This action is permanent.

### Managing subscribers via the API

#### List subscribers

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/platform/newsletter/subscribers \
  -H "X-API-Key: tl_live_your_api_key"
```

Each subscriber in the response includes:

| Field           | Type   | Description                                          |
| :-------------- | :----- | :--------------------------------------------------- |
| `id`            | string | Unique subscriber identifier                         |
| `email`         | string | Subscriber's email address                           |
| `name`          | string | Subscriber's display name                            |
| `status`        | string | `ACTIVE`, `UNSUBSCRIBED`, or `BOUNCED`               |
| `source`        | string | How the subscriber was added (e.g. `website`, `api`) |
| `subscribed_at` | string | ISO 8601 timestamp                                   |

#### Get or update a subscriber

```bash theme={null}
# Get a subscriber
curl -X GET https://api.truthlocks.com/v1/platform/newsletter/subscribers/{id} \
  -H "X-API-Key: tl_live_your_api_key"

# Update a subscriber
curl -X PATCH https://api.truthlocks.com/v1/platform/newsletter/subscribers/{id} \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "status": "UNSUBSCRIBED"}'

# Delete a subscriber
curl -X DELETE https://api.truthlocks.com/v1/platform/newsletter/subscribers/{id} \
  -H "X-API-Key: tl_live_your_api_key"
```

## Campaigns

### Creating a campaign

<Steps>
  <Step title="Open the campaign editor">
    Navigate to **Newsletter** in the console and click **New Campaign**, or go to the campaigns section and click **Create Campaign**.
  </Step>

  <Step title="Compose the email">
    Fill in the campaign fields:

    | Field        | Required | Description                                                |
    | :----------- | :------- | :--------------------------------------------------------- |
    | Subject      | Yes      | The email subject line                                     |
    | Preview text | No       | Short summary that appears in email clients before opening |
    | Content      | Yes      | HTML email body — a live preview renders below the editor  |
  </Step>

  <Step title="Save as draft">
    Click **Create Campaign** to save. The campaign is created in `DRAFT` status.
  </Step>
</Steps>

### Campaign statuses

| Status    | Description                                                              |
| :-------- | :----------------------------------------------------------------------- |
| `DRAFT`   | Not yet sent — you can still edit the subject, preview text, and content |
| `SENDING` | Delivery is in progress                                                  |
| `SENT`    | Successfully delivered to subscribers                                    |
| `FAILED`  | Delivery encountered an error                                            |

### Editing a draft campaign

Open a `DRAFT` campaign from the campaigns list. Update the subject, preview text, or HTML content, then click **Save Changes**. You can also delete a draft campaign entirely.

### Sending a test email

Before broadcasting to your full subscriber list, send a test email to verify the content renders correctly:

1. Open the campaign detail page.
2. Enter a test recipient email address.
3. Click **Send Test**.

The test email is delivered only to the address you specify — no subscribers receive it.

### Broadcasting a campaign

When you are ready to send to all active subscribers:

1. Open the campaign detail page.
2. Click **Send to All Subscribers**.
3. Confirm in the dialog that appears.

<Warning>
  Sending is irreversible. Once confirmed, the campaign is delivered to every active subscriber. Always send a test email first to verify formatting.
</Warning>

After sending, the campaign status changes to `SENT` and the detail page shows delivery stats:

| Metric  | Description                             |
| :------ | :-------------------------------------- |
| Sent    | Number of emails successfully delivered |
| Failed  | Number of delivery failures             |
| Sent at | Timestamp when the broadcast completed  |

### Managing campaigns via the API

#### Create a campaign

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/platform/newsletter/campaigns \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "March product update",
    "preview_text": "New features shipping this week",
    "content": "<h1>March Update</h1><p>Here is what shipped this month...</p>"
  }'
```

| Field          | Type   | Required | Description                         |
| :------------- | :----- | :------- | :---------------------------------- |
| `subject`      | string | Yes      | Email subject line                  |
| `preview_text` | string | No       | Preview text shown in email clients |
| `content`      | string | Yes      | HTML email body                     |

#### List campaigns

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/platform/newsletter/campaigns \
  -H "X-API-Key: tl_live_your_api_key"
```

Each campaign in the response includes:

| Field          | Type           | Description                                     |
| :------------- | :------------- | :---------------------------------------------- |
| `id`           | string         | Unique campaign identifier                      |
| `subject`      | string         | Email subject line                              |
| `preview_text` | string         | Preview text                                    |
| `status`       | string         | `DRAFT`, `SENDING`, `SENT`, or `FAILED`         |
| `sent_count`   | integer        | Number of emails delivered                      |
| `failed_count` | integer        | Number of delivery failures                     |
| `created_at`   | string         | ISO 8601 timestamp                              |
| `sent_at`      | string or null | ISO 8601 timestamp when the broadcast completed |

#### Get, update, or delete a campaign

```bash theme={null}
# Get a campaign
curl -X GET https://api.truthlocks.com/v1/platform/newsletter/campaigns/{id} \
  -H "X-API-Key: tl_live_your_api_key"

# Update a draft campaign
curl -X PATCH https://api.truthlocks.com/v1/platform/newsletter/campaigns/{id} \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Updated subject line"}'

# Delete a campaign
curl -X DELETE https://api.truthlocks.com/v1/platform/newsletter/campaigns/{id} \
  -H "X-API-Key: tl_live_your_api_key"
```

#### Send a test email

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/platform/newsletter/campaigns/{id}/test \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"test_email": "you@example.com"}'
```

#### Send to all subscribers

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/platform/newsletter/campaigns/{id}/send \
  -H "X-API-Key: tl_live_your_api_key"
```

<Warning>
  This broadcasts to every active subscriber and cannot be undone.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="AI CMO" icon="robot" href="/guides/ai-cmo">
    Autonomous outbound campaigns with AI-driven lead discovery and personalized emails.
  </Card>

  <Card title="Email delivery" icon="envelope" href="/security/email-delivery">
    Email infrastructure, templates, and delivery configuration.
  </Card>
</CardGroup>