Use Case 3: Campaigns

Build your own email sequencer using the Outreach2day API. Create multi-step campaigns, import leads, attach mailboxes, launch, and track analytics — all programmatically.

Prerequisites

Active workspace with mailboxes and warmup enabled (see Mailboxes & Domains)

API key with access to the workspace

Flow Overview

Create campaign → Add steps (email templates) → Import contacts (leads)
→ Attach mailboxes → Set schedule → Preflight check → Launch
→ Track analytics → Read replies in Unibox

Step 1: Create a Campaign

POST /campaigns?workspaceId=42

Request:

{
  "name": "Q1 SaaS Outreach",
  "priority": "HIGH"
}

Response:

{
  "id": "cmp_abc123",
  "workspaceId": 42,
  "name": "Q1 SaaS Outreach",
  "priority": "HIGH",
  "status": "draft",
  "createdAt": "2026-03-09T10:00:00Z",
  "updatedAt": "2026-03-09T10:00:00Z"
}

Priority values: HIGH, MEDIUM (default), LOW

Step 2: Add Email Steps

Steps define the email sequence. Each step is an email template with a delay:

Add First Step (Initial Email)

POST /campaigns/cmp_abc123/steps?workspaceId=42

Request:

{
  "order": 1,
  "subject": "Quick question about {{company}}",
  "bodyHtml": "<p>Hi {{firstName}},</p><p>I noticed {{company}} is growing fast. We help companies like yours with...</p><p>Would you be open to a quick chat?</p><p>Best,<br/>{{senderFirstName}}</p>",
  "bodyText": "Hi {{firstName}},\n\nI noticed {{company}} is growing fast. We help companies like yours with...\n\nWould you be open to a quick chat?\n\nBest,\n{{senderFirstName}}"
}

Response:

{
  "id": "stp_001",
  "campaignId": "cmp_abc123",
  "order": 1,
  "subject": "Quick question about {{company}}",
  "bodyHtml": "...",
  "bodyText": "...",
  "delaySeconds": 0,
  "variants": []
}

Add Follow-up Steps

POST /campaigns/cmp_abc123/steps?workspaceId=42

{
  "order": 2,
  "delayDays": 3,
  "subject": "Re: Quick question about {{company}}",
  "bodyHtml": "<p>Hi {{firstName}},</p><p>Just wanted to follow up on my last email. Would love to connect this week.</p><p>{{senderFirstName}}</p>"
}

{
  "order": 3,
  "delayDays": 5,
  "subject": "Last try — {{firstName}}",
  "bodyHtml": "<p>Hi {{firstName}},</p><p>I'll keep this short — is this something worth exploring?</p><p>If not, no worries at all.</p><p>{{senderFirstName}}</p>"
}

A/B Testing with Variants

Add multiple variants to a step to test different messages:

{
  "order": 1,
  "subject": "Quick question about {{company}}",
  "variants": [
    {
      "subject": "Quick question about {{company}}",
      "bodyHtml": "<p>Variant A — direct approach...</p>",
      "weight": 50
    },
    {
      "subject": "Idea for {{company}}",
      "bodyHtml": "<p>Variant B — value-first approach...</p>",
      "weight": 50
    }
  ]
}

Preview an Email

See how an email will look with real contact data before sending:

POST /campaigns/steps/preview?workspaceId=42

Request:

{
  "step": {
    "subject": "Quick question about {{company}}",
    "bodyHtml": "<p>Hi {{firstName}},</p><p>I noticed {{company}} is growing fast...</p>"
  },
  "contact": {
    "firstName": "Sarah",
    "lastName": "Chen",
    "company": "Acme Corp",
    "email": "sarah@acme.com"
  }
}

Response:

{
  "subject": "Quick question about Acme Corp",
  "bodyHtml": "<p>Hi Sarah,</p><p>I noticed Acme Corp is growing fast...</p>"
}

List Steps

GET /campaigns/cmp_abc123/steps?workspaceId=42

Update a Step

PATCH /campaigns/steps/stp_001?workspaceId=42

{
  "subject": "Updated subject line",
  "delayDays": 2
}

Delete a Step

DELETE /campaigns/steps/stp_001?workspaceId=42

Step 3: Import Contacts (Leads)

Quick Import (CSV)

Upload a CSV file with your leads:

POST /campaigns/cmp_abc123/contacts/import?workspaceId=42

Form Data:

Content-Type: multipart/form-data
file: leads.csv
Idempotency-Key: import-batch-001

CSV format:

email,firstName,lastName,company,title
sarah@acme.com,Sarah,Chen,Acme Corp,VP Sales
mike@bigco.io,Mike,Johnson,BigCo,CTO

Response:

{
  "imported": 2,
  "parsed": 2,
  "valid": 2,
  "invalid": 0,
  "upserted": 2
}

Async Import (Large Files)

For large CSV files, use the async import flow:

1. Submit Import

POST /imports?workspaceId=42

Form Data:

campaignId: cmp_abc123
file: large_leads.csv
Idempotency-Key: import-large-001

Response:

{
  "importId": "imp_xyz789",
  "status": "pending_mapping",
  "campaignId": "cmp_abc123"
}

2. Preview Field Mapping

GET /imports/imp_xyz789/mapping-preview?workspaceId=42

Response:

{
  "columns": ["email", "first_name", "last", "org", "role"],
  "suggestedMapping": {
    "email": "email",
    "first_name": "firstName",
    "last": "lastName",
    "org": "company",
    "role": "title"
  },
  "sampleRows": [
    {"email": "sarah@acme.com", "first_name": "Sarah", "last": "Chen", "org": "Acme", "role": "VP"}
  ]
}

3. Confirm Mapping

POST /imports/imp_xyz789/mapping-confirm?workspaceId=42

{
  "mapping": {
    "email": "email",
    "first_name": "firstName",
    "last": "lastName",
    "org": "company",
    "role": "title"
  }
}

4. Check Import Status

GET /imports/imp_xyz789/status?workspaceId=42

{
  "importId": "imp_xyz789",
  "status": "completed",
  "totalRows": 5000,
  "imported": 4950,
  "invalid": 50,
  "errors": [...]
}

List Contacts in Campaign

GET /campaigns/cmp_abc123/contacts?workspaceId=42&limit=50

Response:

{
  "items": [
    {
      "id": "cnt_001",
      "campaignId": "cmp_abc123",
      "email": "sarah@acme.com",
      "name": "Sarah Chen",
      "status": "pending",
      "customJson": {"company": "Acme Corp", "title": "VP Sales"},
      "createdAt": "2026-03-09T10:30:00Z"
    }
  ],
  "next_cursor": "cursor_abc"
}

Contact statuses: pending, active, replied, bounced, unsubscribed, suppressed, completed, failed

Step 4: Attach Mailboxes

Assign sending mailboxes to the campaign:

POST /campaigns/cmp_abc123/mailboxes?workspaceId=42

Request:

{
  "mailboxAddress": "john@cooloutreach.com",
  "dailyLimit": 30,
  "weight": 100
}

Response:

{
  "id": "cmb_001",
  "campaignId": "cmp_abc123",
  "mailboxId": "mbx_501",
  "weight": 100,
  "state": "active",
  "dailyLimit": 30,
  "gapBaseSeconds": 120,
  "gapJitterSeconds": 60
}

Parameters:

Field	Type	Description
`mailboxAddress`	string	Email address of the mailbox
`dailyLimit`	integer	Max emails per day from this mailbox (1-5000)
`weight`	integer	Sending weight relative to other mailboxes (1-1000)
`gapBaseSeconds`	integer	Min seconds between sends (0-86400)
`gapJitterSeconds`	integer	Random jitter added to gap (0-86400)

Add Multiple Mailboxes

Repeat the above for each mailbox. Distributing sends across multiple mailboxes improves deliverability.

Update Mailbox Policy

PATCH /campaigns/cmp_abc123/mailboxes/cmb_001?workspaceId=42

{
  "dailyLimit": 50,
  "weight": 150
}

List Campaign Mailboxes

GET /campaigns/cmp_abc123/mailboxes?workspaceId=42

Step 5: Set Schedule

Define when emails should be sent:

PUT /campaigns/cmp_abc123/schedule?workspaceId=42

Request:

{
  "timezone": "America/New_York",
  "weekdays": ["mon", "tue", "wed", "thu", "fri"],
  "windows": [
    {"start": "09:00", "end": "12:00"},
    {"start": "14:00", "end": "17:00"}
  ]
}

Step 6: Set Stop Rules

Define when to stop emailing a contact:

PUT /campaigns/cmp_abc123/stop-rules?workspaceId=42

Request:

{
  "stopOnReply": true,
  "stopOnUnsub": true,
  "stopOnBounce": true
}

Step 7: Preflight Check

Run preflight checks before launching to catch issues:

GET /campaigns/cmp_abc123/preflight?workspaceId=42

Response:

{
  "checks": [
    {"name": "has_steps", "passed": true},
    {"name": "has_contacts", "passed": true},
    {"name": "has_mailboxes", "passed": true},
    {"name": "mailbox_auth", "passed": true},
    {"name": "schedule_set", "passed": true}
  ],
  "blockingFailures": [],
  "summary": "All checks passed. Ready to launch."
}

If blockingFailures is not empty, fix the issues before launching.

Mailbox Auth Check

Verify mailbox credentials are valid:

GET /campaigns/cmp_abc123/mailbox-preflight?workspaceId=42

Step 8: Launch

POST /campaigns/cmp_abc123/launch?workspaceId=42

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	null	Max contacts to send to (for gradual rollout)
`async`	boolean	false	Return immediately with job ID

Response (sync):

{
  "ok": true,
  "status": "launched",
  "campaignId": "cmp_abc123"
}

Response (async):

{
  "ok": true,
  "jobId": "job_launch_001",
  "status": "queued",
  "campaignId": "cmp_abc123",
  "createdAt": "2026-03-09T11:00:00Z"
}

Check Launch Job Status

GET /campaigns/cmp_abc123/launch-jobs/job_launch_001?workspaceId=42

Step 9: Lifecycle Management

Pause, resume, or stop a running campaign:

POST /campaigns/cmp_abc123/lifecycle?workspaceId=42

Pause:

{"action": "pause"}

Resume:

{"action": "resume"}

Campaign statuses: draft → active → paused / completed / errored

Step 10: Track Analytics

Campaign Stats

GET /campaigns/cmp_abc123/stats?workspaceId=42

Response:

{
  "campaignId": "cmp_abc123",
  "status": "active",
  "contacts": {
    "total": 500,
    "active": 200,
    "completed": 150,
    "replied": 45,
    "bounced": 5
  },
  "sends": {
    "total": 800,
    "sent": 750,
    "failed": 10,
    "bounced": 20,
    "replied": 45
  }
}

List Sent Emails

GET /campaigns/cmp_abc123/sends?workspaceId=42&limit=50

Response:

{
  "items": [
    {
      "id": "snd_001",
      "campaignId": "cmp_abc123",
      "contactId": "cnt_001",
      "stepId": "stp_001",
      "mailboxId": "mbx_501",
      "to": "sarah@acme.com",
      "status": "sent",
      "attempts": 1,
      "sentAt": "2026-03-09T09:15:00Z"
    }
  ],
  "next_cursor": "cursor_xyz"
}

Send statuses: queued, scheduled, sending, sent, failed, bounced, skipped, canceled, replied

Track Contact Changes

Monitor real-time status changes for contacts:

GET /campaigns/cmp_abc123/contacts/changes?workspaceId=42&updatedSince=2026-03-09T00:00:00Z

Response:

{
  "items": [
    {
      "contactId": "cnt_001",
      "email": "sarah@acme.com",
      "status": "replied",
      "previousStatus": "active",
      "updatedAt": "2026-03-09T14:30:00Z"
    }
  ],
  "next_cursor": "cursor_abc",
  "updated_since": "2026-03-09T00:00:00Z"
}

Export Campaign Data

GET /campaigns/cmp_abc123/export?workspaceId=42&kind=summary

Returns a CSV with all contacts and their statuses.

Step 11: Read Replies in Unibox

All prospect replies appear in Unibox. Threads from campaigns include the campaignId field for easy correlation:

GET /threads?workspaceId=42&replyIntent=interested

Threads with campaignId: "cmp_abc123" are replies to this campaign.

Advanced: Webhooks

Get real-time notifications when events happen (reply received, email bounced, etc.):

List Available Event Types

GET /campaigns/webhooks/event-types?workspaceId=42

Create a Webhook

POST /campaigns/webhooks/subscriptions?workspaceId=42

{
  "endpoint": "https://your-app.com/webhooks/outreach",
  "eventTypes": ["reply.received", "contact.bounced", "contact.unsubscribed"],
  "replyIntents": ["interested", "not_interested"],
  "campaignIds": ["cmp_abc123"],
  "ignoreOoo": true,
  "ignoreAutoReply": true,
  "secret": "whsec_your_webhook_secret"
}

Response:

{
  "subscription": {
    "id": "wh_sub_001",
    "endpoint": "https://your-app.com/webhooks/outreach",
    "eventTypes": ["reply.received", "contact.bounced", "contact.unsubscribed"],
    "status": "active",
    "secret": "whsec_your_webhook_secret"
  }
}

Test a Webhook

POST /campaigns/webhooks/subscriptions/wh_sub_001/test?workspaceId=42

Manage Webhooks

PATCH /campaigns/webhooks/subscriptions/{id}?workspaceId=42     # Update
DELETE /campaigns/webhooks/subscriptions/{id}?workspaceId=42    # Delete
POST /campaigns/webhooks/subscriptions/{id}/pause?workspaceId=42   # Pause
POST /campaigns/webhooks/subscriptions/{id}/resume?workspaceId=42  # Resume
POST /campaigns/webhooks/subscriptions/{id}/rotate-secret?workspaceId=42  # Rotate secret

View Webhook Events

GET /campaigns/webhooks/events?workspaceId=42&limit=50

View Deliveries

GET /campaigns/webhooks/subscriptions/{id}/deliveries?workspaceId=42

Advanced: Suppression List

Prevent emails from being sent to specific addresses:

Add to Suppression List

POST /campaigns/suppressions?workspaceId=42

{
  "emails": ["do-not-email@company.com", "unsubscribed@example.com"],
  "reason": "manual_suppression"
}

Check Suppression Status

GET /campaigns/suppressions/status?workspaceId=42&email=someone@company.com

List Suppressions

GET /campaigns/suppressions?workspaceId=42&limit=50

Remove from Suppression

DELETE /campaigns/suppressions?workspaceId=42&email=someone@company.com

Advanced: Subsequences

Create branching flows where contacts move to different sequences based on their behavior:

Create a Subsequence

POST /campaigns/cmp_abc123/subsequences?workspaceId=42

{
  "name": "Interested Follow-up",
  "enrollmentMode": "manual"
}

Set Routing Rules

PATCH /campaigns/cmp_abc123/subsequence-routing?workspaceId=42

{
  "routingPolicy": {
    "rules": [
      {
        "trigger": "reply_intent",
        "value": "interested",
        "subsequenceId": "sub_001"
      }
    ]
  }
}

Complete Python Example: Build a Sequencer

End-to-end example that creates and launches a campaign:

Mailboxes & Domains — set up mailboxes before creating campaigns

Unified Inbox (Unibox) — read and reply to campaign responses

Prerequisites#

Flow Overview#

Step 1: Create a Campaign#

Step 2: Add Email Steps#

Add First Step (Initial Email)#

Add Follow-up Steps#

A/B Testing with Variants#

Preview an Email#

List Steps#

Update a Step#

Delete a Step#

Step 3: Import Contacts (Leads)#

Quick Import (CSV)#

Async Import (Large Files)#

1. Submit Import#

2. Preview Field Mapping#

3. Confirm Mapping#

4. Check Import Status#

List Contacts in Campaign#

Step 4: Attach Mailboxes#

Add Multiple Mailboxes#

Update Mailbox Policy#

List Campaign Mailboxes#

Step 5: Set Schedule#

Step 6: Set Stop Rules#

Step 7: Preflight Check#

Mailbox Auth Check#

Step 8: Launch#

Check Launch Job Status#

Step 9: Lifecycle Management#

Step 10: Track Analytics#

Campaign Stats#

List Sent Emails#

Track Contact Changes#

Export Campaign Data#

Step 11: Read Replies in Unibox#

Advanced: Webhooks#

List Available Event Types#

Create a Webhook#

Test a Webhook#

Manage Webhooks#

View Webhook Events#

View Deliveries#

Advanced: Suppression List#

Add to Suppression List#

Check Suppression Status#

List Suppressions#

Remove from Suppression#

Advanced: Subsequences#

Create a Subsequence#

Set Routing Rules#

Complete Python Example: Build a Sequencer#

Related#

Prerequisites

Flow Overview

Step 1: Create a Campaign

Step 2: Add Email Steps

Add First Step (Initial Email)

Add Follow-up Steps

A/B Testing with Variants

Preview an Email

List Steps

Update a Step

Delete a Step

Step 3: Import Contacts (Leads)

Quick Import (CSV)

Async Import (Large Files)

1. Submit Import

2. Preview Field Mapping

3. Confirm Mapping

4. Check Import Status

List Contacts in Campaign

Step 4: Attach Mailboxes

Add Multiple Mailboxes

Update Mailbox Policy

List Campaign Mailboxes

Step 5: Set Schedule

Step 6: Set Stop Rules

Step 7: Preflight Check

Mailbox Auth Check

Step 8: Launch

Check Launch Job Status

Step 9: Lifecycle Management

Step 10: Track Analytics

Campaign Stats

List Sent Emails

Track Contact Changes

Export Campaign Data

Step 11: Read Replies in Unibox

Advanced: Webhooks

List Available Event Types

Create a Webhook

Test a Webhook

Manage Webhooks

View Webhook Events

View Deliveries

Advanced: Suppression List

Add to Suppression List

Check Suppression Status

List Suppressions

Remove from Suppression

Advanced: Subsequences

Create a Subsequence

Set Routing Rules

Complete Python Example: Build a Sequencer

Related