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

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:

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

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

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:

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

Campaign Execution and Monitoring

Campaign States

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.
• Billing — Understand campaign costs.
• Agent Configuration — Set up the agent that handles campaign responses.