plunk/apps/wiki/content/docs/guides/campaigns.mdx

---
title: Campaigns
description: Send one-time email broadcasts
---

## What are campaigns

Campaigns are one-time email broadcasts sent to your audience. Use them for:
- Product announcements
- Newsletter distributions
- Seasonal promotions
- Feature launches

Unlike workflows (automated sequences), campaigns send once to a snapshot of your audience.

## Creating campaigns

### In the dashboard

1. Go to **Campaigns**
2. Click **Create Campaign**
3. Name your campaign
4. Choose your audience
5. Select a template or compose inline
6. Preview and test
7. Send or schedule

### Via API

```bash
curl -X POST {{API_URL}}/campaigns \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March Newsletter",
    "subject": "New features this month",
    "body": "<h1>What'\''s new</h1><p>Check out our latest updates...</p>",
    "from": "newsletter@example.com",
    "fromName": "Acme Inc",
    "audienceType": "ALL",
    "status": "DRAFT"
  }'
```

## Choosing your audience

### All contacts

Sends to everyone in your project:

```json
{
  "audienceType": "ALL"
}
```

### Specific segment

Sends to contacts in a saved segment:

```json
{
  "audienceType": "SEGMENT",
  "segmentId": "premium-users"
}
```

### Custom filters

Sends to contacts matching conditions:

```json
{
  "audienceType": "FILTERED",
  "audienceFilter": {
    "operator": "AND",
    "conditions": [
      { "field": "data.plan", "operator": "equals", "value": "pro" },
      { "field": "data.lastLoginAt", "operator": "greaterThan", "value": "2024-01-01" }
    ]
  }
}
```

## Subscription handling

Campaign delivery respects your **template type**:

**Marketing templates** (default)
- Only sends to subscribed contacts
- Unsubscribed contacts are skipped automatically
- Includes unsubscribe link

**Transactional templates**
- Sends to all contacts, even if unsubscribed
- Use only for critical business emails
- No unsubscribe link

Choose template type based on content, not audience size.

## Campaign states

**DRAFT** — Being created, can edit freely

**SCHEDULED** — Queued for future send, can cancel

**SENDING** — Currently delivering, cannot stop

**SENT** — Completed successfully

**CANCELLED** — Scheduled campaign was cancelled

## Sending campaigns

### Send immediately

```bash
curl -X POST {{API_URL}}/campaigns/campaign_id/send \
  -H "Authorization: Bearer sk_your_secret_key"
```

Status changes to SENDING, emails deliver within minutes.

### Schedule for later

```bash
curl -X POST {{API_URL}}/campaigns/campaign_id/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2024-03-20T10:00:00Z"
  }'
```

Status changes to SCHEDULED. Campaign sends at the specified time.

### Cancel scheduled campaign

```bash
curl -X POST {{API_URL}}/campaigns/campaign_id/cancel \
  -H "Authorization: Bearer sk_your_secret_key"
```

Only works if status is SCHEDULED.

## Testing campaigns

Send a test email before broadcasting:

```bash
curl -X POST {{API_URL}}/campaigns/campaign_id/test \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com"
  }'
```

This sends to the test email without affecting campaign status.

## Campaign analytics

View campaign performance:

```bash
curl -X GET {{API_URL}}/campaigns/campaign_id/stats \
  -H "Authorization: Bearer sk_your_secret_key"
```

Returns:

```json
{
  "totalRecipients": 5000,
  "sentCount": 5000,
  "deliveredCount": 4980,
  "openedCount": 2100,
  "clickedCount": 450,
  "bouncedCount": 20,
  "openRate": 0.42,
  "clickRate": 0.09
}
```

Metrics update in real-time as recipients engage.

## Managing campaigns

### List campaigns

```bash
curl -X GET {{API_URL}}/campaigns \
  -H "Authorization: Bearer sk_your_secret_key"
```

Filter by status:

```bash
curl -X GET "{{API_URL}}/campaigns?status=SENT" \
  -H "Authorization: Bearer sk_your_secret_key"
```

### Get campaign details

```bash
curl -X GET {{API_URL}}/campaigns/campaign_id \
  -H "Authorization: Bearer sk_your_secret_key"
```

### Update draft campaign

```bash
curl -X PATCH {{API_URL}}/campaigns/campaign_id \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated name",
    "subject": "New subject line"
  }'
```

Only works for DRAFT campaigns.

### Duplicate campaign

```bash
curl -X POST {{API_URL}}/campaigns/campaign_id/duplicate \
  -H "Authorization: Bearer sk_your_secret_key"
```

Creates a new draft campaign with the same content.

### Delete campaign

```bash
curl -X DELETE {{API_URL}}/campaigns/campaign_id \
  -H "Authorization: Bearer sk_your_secret_key"
```

Can only delete DRAFT or CANCELLED campaigns.

## Next Steps

- [Build automated workflows](/guides/workflows)
- [Create dynamic segments](/guides/segments)
- [Track campaign analytics](/guides/analytics)
- [Set up custom domains](/guides/custom-domains)