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 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:

Select the AI agent to use for calls.
Set the opening message (what the agent says first).
Configure the agent’s instructions for the call.
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
Escalation	Notify a human via email and/or webhook when retries are exhausted — see Retry & 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

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 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.

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:

# 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:

curl https://api.thinnest.ai/campaigns/campaign_123/results \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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 — Import and organize your contact lists.
Retry & Escalation — Per-step retry schedules and email/webhook escalation.
Billing — Understand campaign costs.
Agent Configuration — Set up the agent that handles campaign responses.

​Outbound Campaigns

​What Are Campaigns?

​Campaign Types

​Creating a Campaign

​Step 1: Choose a Contact Group

​Step 2: Select Campaign Type

​Step 3: Configure the Message

​SMS Campaigns

​Email Campaigns

​Voice Campaigns

​Step 4: Configure Settings

​Step 5: Schedule or Send

​Via the API

​Template Variables

​Built-in Variables

​Custom Variables

​Scheduling and Timezone Support

​Timezone-Aware Scheduling

​Sending Windows

​Campaign Execution and Monitoring

​Campaign States

​Monitoring a Running Campaign

​Pausing and Resuming

​Campaign Results

​Best Practices

​Next Steps