Campaigns

The Campaigns API allows you to create, manage, and monitor email campaigns at scale.

Base URL

https://api.unsent.dev/v1/campaigns

Features

Campaign creation

Create email campaigns with rich content

Scheduling

Schedule campaigns for optimal delivery times

Batch processing

Send to large contact lists efficiently

Campaign control

Pause, resume, and monitor active campaigns

Performance tracking

Real-time delivery and engagement metrics

Personalization

Use contact data for dynamic content

Quick Start

Create a simple campaign

curl -X POST https://api.unsent.dev/v1/campaigns \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Campaign",
    "from": "welcome@yourdomain.com",
    "subject": "Welcome to our service!",
    "contactBookId": "cb_123456789",
    "html": "<h1>Welcome {{firstName}}!</h1><p>Thanks for joining us.</p>",
    "sendNow": true
  }'

Schedule a campaign for later

curl -X POST https://api.unsent.dev/v1/campaigns \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Newsletter",
    "from": "newsletter@yourdomain.com",
    "subject": "Your December Newsletter",
    "contactBookId": "cb_123456789",
    "html": "<html>...</html>",
    "scheduledAt": "2024-12-01T09:00:00Z",
    "batchSize": 1000
  }'

Schedule an existing campaign

curl -X POST https://api.unsent.dev/v1/campaigns/{campaignId}/schedule \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "tomorrow 10:00 AM",
    "batchSize": 500
  }'

Pause a running campaign

curl -X POST https://api.unsent.dev/v1/campaigns/{campaignId}/pause \
  -H "Authorization: Bearer your-api-key"

Resume a paused campaign

curl -X POST https://api.unsent.dev/v1/campaigns/{campaignId}/resume \
  -H "Authorization: Bearer your-api-key"

API Endpoints

Campaign Personalization

Use contact properties to personalize your campaigns:

<html>
  <body>
    <h1>Hi {{firstName}} {{lastName}}!</h1>
    <p>As a {{properties.tier}} member, you have access to exclusive benefits.</p>
    <p>Your last purchase was on: {{properties.last_purchase_date}}</p>
  </body>
</html>

Available Variables

firstName - Contact's first name
lastName - Contact's last name
email - Contact's email address
properties.* - Any custom contact property

Campaign Management

Campaign Status

DRAFT - Campaign created but not scheduled
SCHEDULED - Campaign scheduled for future delivery
SENDING - Campaign actively sending emails
PAUSED - Campaign temporarily stopped
COMPLETED - Campaign finished sending
FAILED - Campaign failed to send

Batch Processing

Control how emails are sent:

batchSize - Number of emails per batch (1-100,000)
batchWindowMinutes - Minutes between batches
Natural language scheduling - "tomorrow 9am", "next monday"

Performance Tracking

Monitor campaign performance with real-time metrics:

Delivery Metrics

total - Total recipients
sent - Emails sent successfully
delivered - Emails delivered to inbox
bounced - Hard and soft bounces

Engagement Metrics

opened - Emails opened by recipients
clicked - Links clicked in emails
unsubscribed - Recipients who unsubscribed
complained - Spam complaints

Example Campaign Stats

{
  "id": "cmp_123456789",
  "name": "Welcome Campaign",
  "status": "COMPLETED",
  "total": 10000,
  "sent": 10000,
  "delivered": 9850,
  "opened": 6200,
  "clicked": 1850,
  "unsubscribed": 45,
  "bounced": 150,
  "complained": 5
}

Scheduling Best Practices

Optimal Send Times

Tuesday-Thursday: Highest engagement rates
10 AM - 2 PM: Peak email checking hours
Avoid: Monday mornings, weekends

Natural Language Scheduling

Use flexible scheduling:

"tomorrow 9am"
"next monday 10:30 AM"
"December 25, 2024 09:00:00Z"

Rate Limits

Campaign creation: 10 campaigns per hour
Campaign management: 100 operations per hour
Campaign retrieval: 200 requests per hour

Best Practices

Content Optimization

Use responsive design for mobile devices
Include plain text version alongside HTML
Personalize with contact data for better engagement
Test spam score before sending
Include clear unsubscribe links

Delivery Optimization

Warm up new sending domains gradually
Monitor bounce rates and remove invalid addresses
Use appropriate batch sizes for your contact list
Schedule during optimal hours for your audience
Test with small segments first

Compliance

Include physical address in emails
Honor unsubscribe requests promptly
Get explicit consent before adding contacts
Follow GDPR/CCPA regulations as applicable

Common Use Cases

Welcome Series

{
  "name": "Welcome Email 1",
  "subject": "Welcome to {{properties.company_name}}!",
  "html": "<h1>Hi {{firstName}}, welcome aboard!</h1>",
  "sendNow": true
}

{
  "name": "December Newsletter",
  "subject": "Your monthly updates from {{properties.company_name}}",
  "html": "<p>Here are this month highlights...</p>",
  "scheduledAt": "2024-12-01T10:00:00Z",
  "batchSize": 2000
}

Product Announcements

{
  "name": "New Feature Launch",
  "subject": "Introducing our new {{properties.feature_name}}!",
  "html": "<h1>Exciting news!</h1><p>We just launched...</p>",
  "sendNow": true,
  "batchSize": 500
}