Campaign Setup Guide

This guide walks you through setting up a complete cold email campaign using the API — from creating the campaign to sending your first emails.

Overview

A campaign consists of five parts that need to be configured in order:

Create the campaign

Define name, timezone, sending schedule, and daily limits.

Add sequence steps

Create the email chain — initial outreach, follow-ups, and final touches.

Add leads

Assign leads (contacts) to the campaign.

Assign email accounts

Choose which email accounts will send the campaign emails.

Start the campaign

Transition the campaign from draft to active — emails begin sending.

Step 1: Create a Campaign

Create a new campaign in draft status. It won’t send anything until you start it.

curl -X POST "https://api.foxreach.io/api/v1/campaigns" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Enterprise Outreach",
    "timezone": "America/New_York",
    "sendingDays": [1, 2, 3, 4, 5],
    "sendingStartHour": 9,
    "sendingEndHour": 17,
    "dailyLimit": 50
  }'

from foxreach import FoxReach, CampaignCreate

client = FoxReach(api_key="otr_your_key")

campaign = client.campaigns.create(CampaignCreate(
    name="Q1 Enterprise Outreach",
    timezone="America/New_York",
    sending_days=[1, 2, 3, 4, 5],
    sending_start_hour=9,
    sending_end_hour=17,
    daily_limit=50,
))
print(f"Campaign created: {campaign.id} (status: {campaign.status})")

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });

const campaign = await client.campaigns.create({
  name: "Q1 Enterprise Outreach",
  timezone: "America/New_York",
  sendingDays: [1, 2, 3, 4, 5],
  sendingStartHour: 9,
  sendingEndHour: 17,
  dailyLimit: 50,
});
console.log(`Campaign created: ${campaign.id} (status: ${campaign.status})`);

Save the campaign.id — you’ll need it for all subsequent steps. To send each lead’s first email from a mailbox on the same provider (Google or Microsoft) when one has capacity, add "espMatching": true to the request, or turn it on later with Update Campaign while the campaign is a draft or paused. Follow-ups always stay with the mailbox that sent the first email.

Step 2: Add Sequence Steps

Sequences define the emails in your campaign. Each step has a subject, body, and delay (days to wait after the previous step).

from foxreach import SequenceCreate

# Step 1: Initial outreach (sent immediately)
step1 = client.campaigns.sequences.create(campaign.id, SequenceCreate(
    subject="Quick question about {{company}}",
    body="Hi {{firstName}},\n\nI noticed {{company}} is growing fast. We help companies like yours with cold email outreach.\n\nWould you be open to a quick chat this week?\n\nBest,\n[Your Name]",
    delay_days=0,
))

# Step 2: Follow-up (3 days later)
step2 = client.campaigns.sequences.create(campaign.id, SequenceCreate(
    subject="Re: Quick question about {{company}}",
    body="Hi {{firstName}},\n\nJust following up on my last email. I know you're busy — would a 15-minute call work better?\n\nHere's a link to book time: [calendar link]\n\nCheers,\n[Your Name]",
    delay_days=3,
))

# Step 3: Final touch (5 days later)
step3 = client.campaigns.sequences.create(campaign.id, SequenceCreate(
    subject="Last try — {{firstName}}",
    body="Hi {{firstName}},\n\n{I understand if this isn't a priority right now|No worries if the timing isn't right}. I'll leave the door open — feel free to reach out anytime.\n\nBest,\n[Your Name]",
    delay_days=5,
))

print(f"Added 3 sequence steps")

// Step 1: Initial outreach (sent immediately)
const step1 = await client.campaigns.sequences.create(campaign.id, {
  subject: "Quick question about {{company}}",
  body: "Hi {{firstName}},\n\nI noticed {{company}} is growing fast. We help companies like yours with cold email outreach.\n\nWould you be open to a quick chat this week?\n\nBest,\n[Your Name]",
  delayDays: 0,
});

// Step 2: Follow-up (3 days later)
const step2 = await client.campaigns.sequences.create(campaign.id, {
  subject: "Re: Quick question about {{company}}",
  body: "Hi {{firstName}},\n\nJust following up on my last email. I know you're busy — would a 15-minute call work better?\n\nHere's a link to book time: [calendar link]\n\nCheers,\n[Your Name]",
  delayDays: 3,
});

// Step 3: Final touch (5 days later)
const step3 = await client.campaigns.sequences.create(campaign.id, {
  subject: "Last try — {{firstName}}",
  body: `Hi {{firstName}},\n\n{I understand if this isn't a priority right now|No worries if the timing isn't right}. I'll leave the door open — feel free to reach out anytime.\n\nBest,\n[Your Name]`,
  delayDays: 5,
});

console.log("Added 3 sequence steps");

Use template variables like {{firstName}} and {{company}} for personalization. Use spin syntax like {option1|option2} for unique variations that improve deliverability.

Step 3: Add Leads

Add leads to the campaign by their IDs. If you haven’t created leads yet, do that first using the Leads API.

lead_ids = ["cld_lead1", "cld_lead2", "cld_lead3"]
result = client.campaigns.add_leads(campaign.id, lead_ids)
print(f"Added {len(lead_ids)} leads to campaign")

const leadIds = ["cld_lead1", "cld_lead2", "cld_lead3"];
const result = await client.campaigns.addLeads(campaign.id, leadIds);
console.log(`Added ${leadIds.length} leads to campaign`);

Leads that are already enrolled in the campaign will be skipped (no duplicates).

Step 4: Assign Email Accounts

Assign one or more email accounts to send the campaign emails. The campaign will rotate between assigned accounts. With provider matching on (espMatching), each lead’s first email goes out from an assigned mailbox on the lead’s own provider when one has capacity.

account_ids = ["acc_sender1"]
result = client.campaigns.add_accounts(campaign.id, account_ids)
print(f"Assigned {len(account_ids)} email account(s)")

const accountIds = ["acc_sender1"];
const result = await client.campaigns.addAccounts(campaign.id, accountIds);
console.log(`Assigned ${accountIds.length} email account(s)`);

Use client.email_accounts.list() (Python) or client.emailAccounts.list() (TypeScript) to see your available accounts and their health scores.

Step 5: Start the Campaign

Once everything is configured, start the campaign. Emails will begin sending according to the schedule and daily limits.

campaign = client.campaigns.start(campaign.id)
print(f"Campaign started! Status: {campaign.status}")

client.close()

const started = await client.campaigns.start(campaign.id);
console.log(`Campaign started! Status: ${started.status}`);

Make sure your sequence steps, leads, and email accounts are all configured before starting. You can’t edit an active campaign — pause it first.

Monitoring Performance

After your campaign is running, check its performance:

stats = client.analytics.campaign(campaign.id)
print(f"Sent: {stats.sent}")
print(f"Delivered: {stats.delivered}")
print(f"Replied: {stats.replied}")
print(f"Reply rate: {stats.reply_rate:.1f}%")
print(f"Bounce rate: {stats.bounce_rate:.1f}%")

const stats = await client.analytics.campaign(campaign.id);
console.log(`Sent: ${stats.sent}`);
console.log(`Delivered: ${stats.delivered}`);
console.log(`Replied: ${stats.replied}`);
console.log(`Reply rate: ${stats.replyRate.toFixed(1)}%`);
console.log(`Bounce rate: ${stats.bounceRate.toFixed(1)}%`);

Next Steps

Template Variables

Learn about personalization variables and spin syntax for better deliverability.

Inbox Management

Monitor and categorize replies from your campaign.

Webhooks

Get real-time notifications when emails are sent, replies come in, or campaigns complete.

Analytics

View dashboard-level KPIs across all your campaigns.

Getting started

API guides

Leads

Campaigns

Sequences

Campaign Leads

Campaign Accounts

Inbox

Email Accounts

Lead Finder

Tracking Domains

Warmup

Managed Mailboxes

Templates

Analytics

Webhooks API

Overview

Step 1: Create a Campaign

Step 2: Add Sequence Steps

Step 3: Add Leads

Step 4: Assign Email Accounts

Step 5: Start the Campaign

Monitoring Performance

Next Steps

Template Variables

Inbox Management

Webhooks

Analytics

​Overview

​Step 1: Create a Campaign

​Step 2: Add Sequence Steps

​Step 3: Add Leads

​Step 4: Assign Email Accounts

​Step 5: Start the Campaign

​Monitoring Performance

​Next Steps

Template Variables

Inbox Management

Webhooks

Analytics

Overview

Step 1: Create a Campaign

Step 2: Add Sequence Steps

Step 3: Add Leads

Step 4: Assign Email Accounts

Step 5: Start the Campaign

Monitoring Performance

Next Steps