Campaigns

Create, schedule, and manage email marketing campaigns to your audiences.

Create a Campaign

Create a new campaign to send to an audience.

POST /v1/campaigns

create-campaign.ts

const campaign = await client.campaigns.create({
  name: 'December Newsletter',
  subject: 'Our December Updates',
  from: 'news@yourdomain.com',
  replyTo: 'support@yourdomain.com',
  audienceId: 'audience_xxxxx',
  templateId: 'template_xxxxx',
  variables: {
    month: 'December',
    year: 2024,
  },
  previewText: 'See what we shipped this month...',
  tags: ['newsletter', 'monthly'],
});

You can also provide HTML directly instead of using a template:

create-campaign-html.ts

const campaign = await client.campaigns.create({
  name: 'Product Launch',
  subject: 'Introducing our new feature',
  from: 'news@yourdomain.com',
  audienceId: 'audience_xxxxx',
  html: `
    <h1>Exciting News!</h1>
    <p>We just launched a new feature...</p>
  `,
  text: 'Exciting News! We just launched a new feature...',
});

Campaign Lifecycle

Campaigns progress through the following statuses:

Status	Description
`draft`	Campaign is being edited
`scheduled`	Campaign is scheduled for future delivery
`sending`	Campaign is currently being sent
`sent`	Campaign has been sent to all recipients
`paused`	Campaign sending is paused
`cancelled`	Campaign was cancelled

Schedule a Campaign

Schedule a campaign to be sent at a specific time.

POST /v1/campaigns/:id/schedule

schedule-campaign.ts

const campaign = await client.campaigns.schedule('campaign_xxxxx', {
  scheduledAt: '2024-12-25T09:00:00Z',
});

console.log(campaign.status); // 'scheduled'
console.log(campaign.scheduledAt); // '2024-12-25T09:00:00Z'

Send Immediately

Send a campaign to all subscribers immediately.

POST /v1/campaigns/:id/send

send-campaign.ts

const campaign = await client.campaigns.send('campaign_xxxxx');

console.log(campaign.status); // 'sending'

Pause and Resume

Pause a campaign that is currently sending, then resume when ready.

pause-resume-campaign.ts

// Pause a sending campaign
await client.campaigns.pause('campaign_xxxxx');

// Resume the paused campaign
await client.campaigns.resume('campaign_xxxxx');

Cancel a Campaign

Cancel a scheduled or sending campaign. Emails already sent cannot be recalled.

POST /v1/campaigns/:id/cancel

cancel-campaign.ts

await client.campaigns.cancel('campaign_xxxxx');

Campaign Analytics

Get detailed statistics for a campaign.

campaign-analytics.ts

const campaign = await client.campaigns.get('campaign_xxxxx');

console.log(campaign.stats);
// {
//   total: 1000,      // Total recipients
//   sent: 1000,       // Emails sent
//   delivered: 985,   // Emails delivered
//   opened: 450,      // Unique opens
//   clicked: 120,     // Unique clicks
//   bounced: 15,      // Bounced emails
//   complained: 2,    // Spam complaints
//   unsubscribed: 8,  // Unsubscribes
// }

List Campaigns

GET /v1/campaigns

list-campaigns.ts

const { data } = await client.campaigns.list();

for (const campaign of data) {
  console.log(`${campaign.name}: ${campaign.status}`);
}