> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foxreach.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Campaign Setup Guide
> End-to-end guide for creating and launching a cold email campaign via the FoxReach API.
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:
Define name, timezone, sending schedule, and daily limits.
Create the email chain — initial outreach, follow-ups, and final touches.
Assign leads (contacts) to the campaign.
Choose which email accounts will send the campaign emails.
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.
```bash cURL theme={null}
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
}'
```
```python Python SDK theme={null}
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})")
```
```typescript TypeScript SDK theme={null}
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.
## 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).
```python Python SDK theme={null}
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")
```
```typescript TypeScript SDK theme={null}
// 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](/template-variables) like `{{firstName}}` and `{{company}}` for personalization. Use [spin syntax](/template-variables#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](/api-reference/leads/create-lead).
```python Python SDK theme={null}
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")
```
```typescript TypeScript SDK theme={null}
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.
```python Python SDK theme={null}
account_ids = ["acc_sender1"]
result = client.campaigns.add_accounts(campaign.id, account_ids)
print(f"Assigned {len(account_ids)} email account(s)")
```
```typescript TypeScript SDK theme={null}
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.
```python Python SDK theme={null}
campaign = client.campaigns.start(campaign.id)
print(f"Campaign started! Status: {campaign.status}")
client.close()
```
```typescript TypeScript SDK theme={null}
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:
```python Python SDK theme={null}
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}%")
```
```typescript TypeScript SDK theme={null}
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
Learn about personalization variables and spin syntax for better deliverability.
Monitor and categorize replies from your campaign.
Get real-time notifications when emails are sent, replies come in, or campaigns complete.
View dashboard-level KPIs across all your campaigns.