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

# Outbound Campaigns

> Create and manage outbound campaigns to reach your contacts via SMS, email, and voice using AI-powered personalization.

# Outbound Campaigns

Campaigns let you proactively reach out to your contacts through SMS, email, and voice calls. Instead of waiting for users to come to you, your AI agents go to them — with personalized messages at scale.

## What Are Campaigns?

A campaign is a batch outreach operation. You define:

* **Who** to contact (a contact group)
* **How** to reach them (SMS, email, or voice)
* **What** to say (a message template with personalization)
* **When** to send (immediate or scheduled)

Your AI agent handles each conversation individually, personalizing responses and following up based on the contact's replies.

## Campaign Types

| Type      | Description                   | Best For                                                       |
| --------- | ----------------------------- | -------------------------------------------------------------- |
| **SMS**   | Text message campaigns        | Appointment reminders, quick notifications, surveys            |
| **Email** | Email outreach with templates | Newsletter, onboarding sequences, announcements                |
| **Voice** | Automated AI phone calls      | Sales outreach, appointment confirmations, feedback collection |

## Creating a Campaign

### Step 1: Choose a Contact Group

Select or create a group of contacts to reach. See [Contact Management](/docs/campaigns/contact-management) for details on importing and organizing contacts.

### Step 2: Select Campaign Type

Choose SMS, email, or voice. Each type has different configuration options.

### Step 3: Configure the Message

#### SMS Campaigns

Write your message template with personalization variables:

```
Hi {{first_name}}, this is {{agent_name}} from {{company}}.
Your appointment is scheduled for {{appointment_date}}.
Reply CONFIRM to confirm or RESCHEDULE to pick a new time.
```

#### Email Campaigns

Configure subject line, body, and optional HTML template:

```
Subject: {{first_name}}, your trial is ending soon

Hi {{first_name}},

Your free trial of {{plan_name}} expires on {{expiry_date}}.
Upgrade now to keep your agents running.

Best,
{{agent_name}}
```

#### Voice Campaigns

For voice campaigns, you configure the agent that will make the calls:

1. Select the AI agent to use for calls.
2. Set the opening message (what the agent says first).
3. Configure the agent's instructions for the call.
4. Set call duration limits.

### Step 4: Configure Settings

| Setting            | Description                                                                                                                         |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Campaign Name**  | Internal name for tracking                                                                                                          |
| **Agent**          | The AI agent handling responses                                                                                                     |
| **Caller ID**      | Phone number or email sender identity                                                                                               |
| **Retry Schedule** | Per-step list of delays for failed deliveries — see [Retry & Escalation](/docs/campaigns/retry-and-escalation)                      |
| **Escalation**     | Notify a human via email and/or webhook when retries are exhausted — see [Retry & Escalation](/docs/campaigns/retry-and-escalation) |

### Step 5: Schedule or Send

Choose when to execute the campaign:

* **Send Now**: Starts immediately.
* **Schedule**: Pick a date and time.
* **Recurring**: Set up daily, weekly, or monthly execution.

### Via the API

```bash theme={null}
curl -X POST https://api.thinnest.ai/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminders",
    "type": "sms",
    "agent_id": "agent_abc123",
    "contact_group_id": "group_xyz789",
    "message_template": "Hi {{first_name}}, your appointment is on {{date}}. Reply CONFIRM or RESCHEDULE.",
    "scheduled_at": "2026-03-10T09:00:00Z",
    "timezone": "America/New_York"
  }'
```

## Template Variables

Personalize your messages with contact fields and custom variables.

### Built-in Variables

| Variable         | Description               |
| ---------------- | ------------------------- |
| `{{first_name}}` | Contact's first name      |
| `{{last_name}}`  | Contact's last name       |
| `{{email}}`      | Contact's email address   |
| `{{phone}}`      | Contact's phone number    |
| `{{company}}`    | Contact's company name    |
| `{{agent_name}}` | The name of your AI agent |

### Custom Variables

Add custom fields to your contacts and use them in templates:

```
Hi {{first_name}}, your order #{{order_number}} has shipped.
Estimated delivery: {{delivery_date}}.
```

Custom variables are pulled from the contact's metadata. Set them during [CSV import](/docs/campaigns/contact-management) or via the API.

## Scheduling and Timezone Support

### Timezone-Aware Scheduling

Campaigns respect your contacts' timezones. When you schedule a campaign for "9:00 AM", each contact receives the message at 9:00 AM in their local timezone.

```bash theme={null}
curl -X POST https://api.thinnest.ai/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Check-in",
    "type": "sms",
    "agent_id": "agent_abc123",
    "contact_group_id": "group_xyz789",
    "message_template": "Good morning {{first_name}}! How are you feeling today?",
    "scheduled_at": "2026-03-10T09:00:00",
    "timezone": "contact_local",
    "sending_window": {
      "start_hour": 9,
      "end_hour": 17
    }
  }'
```

### Sending Windows

Restrict message delivery to appropriate hours:

| Setting         | Description                                   |
| --------------- | --------------------------------------------- |
| `start_hour`    | Earliest hour to send (e.g., `9` for 9 AM)    |
| `end_hour`      | Latest hour to send (e.g., `17` for 5 PM)     |
| `excluded_days` | Days to skip (e.g., `["Saturday", "Sunday"]`) |

Messages that fall outside the window are queued and sent when the window opens.

## Campaign Execution and Monitoring

### Campaign States

| State         | Description                         |
| ------------- | ----------------------------------- |
| **Draft**     | Saved but not scheduled             |
| **Scheduled** | Queued for future execution         |
| **Running**   | Actively sending messages           |
| **Paused**    | Temporarily halted (can be resumed) |
| **Completed** | All messages sent                   |
| **Failed**    | Execution encountered errors        |

### Monitoring a Running Campaign

Track your campaign's progress from the dashboard:

* **Sent**: Number of messages delivered
* **Delivered**: Confirmed delivery count
* **Replied**: Number of contacts who responded
* **Failed**: Messages that couldn't be delivered
* **Pending**: Messages still in queue

### Pausing and Resuming

If something looks wrong, pause the campaign immediately:

```bash theme={null}
# Pause
curl -X POST https://api.thinnest.ai/campaigns/campaign_123/pause \
  -H "Authorization: Bearer YOUR_API_KEY"

# Resume
curl -X POST https://api.thinnest.ai/campaigns/campaign_123/resume \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Pausing stops all pending messages. Already-sent messages are not affected.

### Campaign Results

After a campaign completes, review the results:

```bash theme={null}
curl https://api.thinnest.ai/campaigns/campaign_123/results \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "campaign_id": "campaign_123",
  "status": "completed",
  "total_contacts": 500,
  "sent": 498,
  "delivered": 485,
  "replied": 142,
  "failed": 2,
  "reply_rate": "29.3%",
  "average_response_time": "4m 23s"
}
```

## Best Practices

* **Start small**: Test with a small group before sending to your full list.
* **Personalize**: Messages with the contact's name get significantly higher response rates.
* **Respect time zones**: Nobody wants a business text at 3 AM.
* **Set sending windows**: Restrict to business hours for professional outreach.
* **Monitor actively**: Watch the first few minutes of a campaign for issues.
* **Handle opt-outs**: Always include an opt-out mechanism (required by law for SMS).

## Next Steps

* [Contact Management](/docs/campaigns/contact-management) — Import and organize your contact lists.
* [Retry & Escalation](/docs/campaigns/retry-and-escalation) — Per-step retry schedules and email/webhook escalation.
* [Billing](/docs/billing) — Understand campaign costs.
* [Agent Configuration](/docs/agents) — Set up the agent that handles campaign responses.