Skip to main content

​
Overview

The Campaigns API allows you to create targeted email campaigns, send test emails, and launch mass communications to segmented audiences.

​
Campaign Operations

​
getAll

Retrieve all campaigns. 
db.campaigns.getAll(): Campaign[]
​
campaigns
Campaign[]
Array of all campaigns
Example: 
const campaigns = db.campaigns.getAll();
console.log(`Total campaigns: ${campaigns.length}`);

​
getById

Get a specific campaign by ID. 
db.campaigns.getById(id: string): Campaign | undefined
​
id
string
required
Campaign ID
​
campaign
Campaign | undefined
The campaign object if found
Example: 
const campaign = db.campaigns.getById('camp_123');
if (campaign) {
  console.log('Campaign:', campaign.name);
}

​
create

Create a new campaign. 
db.campaigns.create(
  data: Omit<Campaign, 'id' | 'createdAt' | 'metrics'>
): Campaign
​
data.name
string
required
Internal campaign name
​
data.subject
string
required
Email subject line
​
data.content
string
required
HTML email content
​
data.status
string
required
Campaign status: ‘Draft’ | ‘Scheduled’ | ‘Sent’ | ‘Testing’
​
data.recipientType
string
required
Target audience: ‘all’ | ‘subscribed’ | ‘list’
​
data.listId
string
Required if recipientType is ‘list’
​
data.recipientCount
number
required
Initial recipient count (set to 0)
​
campaign
Campaign
The created campaign with ID and timestamps
Example: 
const campaign = db.campaigns.create({
  name: 'March Newsletter 2024',
  subject: 'Novedades de Marzo - CAFH',
  content: '<h1>Boletín de Marzo</h1><p>Contenido...</p>',
  status: 'Draft',
  recipientType: 'subscribed',
  recipientCount: 0
});

​
save

Update an existing campaign. 
db.campaigns.save(campaign: Campaign): Campaign
​
campaign
Campaign
required
Complete campaign object with updates
​
campaign
Campaign
The updated campaign
Example: 
const campaign = db.campaigns.getById('camp_123');
if (campaign) {
  campaign.subject = 'Updated Subject';
  campaign.status = 'Testing';
  db.campaigns.save(campaign);
}

​
delete

Delete a campaign. 
db.campaigns.delete(id: string): void
​
id
string
required
Campaign ID to delete
Example: 
db.campaigns.delete('camp_123');

​
Testing & Launch

​
sendTest

Send a test email before launching. 
db.campaigns.sendTest(
  campaignId: string,
  testEmail: string
): Promise<void>
​
campaignId
string
required
ID of the campaign to test
​
testEmail
string
required
Email address to send test to
Example: 
await db.campaigns.sendTest('camp_123', '[email protected]');
console.log('Test email sent');
Test emails are sent with “[TEST]” prefix in the subject line.

​
launch

Launch a campaign to all targeted recipients. 
db.campaigns.launch(
  campaignId: string
): Promise<{ recipientCount: number }>
​
campaignId
string
required
ID of the campaign to launch
​
result
object
Object containing the number of recipients
Example: 
const result = await db.campaigns.launch('camp_123');
console.log(`Campaign launched to ${result.recipientCount} recipients`);
How It Works:
  1. Determines recipients based on recipientType:
    • 'all' → All contacts in CRM
    • 'subscribed' → Only contacts with status ‘Subscribed’
    • 'list' → Contacts in the specified list
  2. Creates email log entries for each recipient
  3. Queues emails via backend API
  4. Updates campaign status to ‘Sent’ with metrics

​
Campaign Type

interface Campaign {
  id: string;
  name: string;          // Internal name
  subject: string;       // Email subject
  content: string;       // HTML content
  status: 'Draft' | 'Scheduled' | 'Sent' | 'Testing';
  recipientType: 'all' | 'subscribed' | 'list';
  listId?: string;       // If recipientType === 'list'
  recipientCount: number; // Snapshot at send time
  createdAt: string;
  sentAt?: string;
  scheduledAt?: string;
  testEmail?: string;    // Last test recipient
  metrics: {
    sent: number;
    opened: number;
    clicked: number;
    bounced: number;
  };
}

​
Recipient Targeting

​
All Contacts

db.campaigns.create({
  name: 'Announcement',
  subject: 'Important Update',
  content: '<p>...</p>',
  status: 'Draft',
  recipientType: 'all',
  recipientCount: 0
});

​
Subscribed Only

db.campaigns.create({
  name: 'Newsletter',
  subject: 'Monthly News',
  content: '<p>...</p>',
  status: 'Draft',
  recipientType: 'subscribed',
  recipientCount: 0
});

​
Specific List

db.campaigns.create({
  name: 'VIP Event Invite',
  subject: 'Exclusive Invitation',
  content: '<p>...</p>',
  status: 'Draft',
  recipientType: 'list',
  listId: 'list_vip_members',
  recipientCount: 0
});

​
Workflow Example

// 1. Create campaign
const campaign = db.campaigns.create({
  name: 'Spring Campaign 2024',
  subject: 'New Season, New Beginnings',
  content: '<h1>Spring Newsletter</h1>',
  status: 'Draft',
  recipientType: 'subscribed',
  recipientCount: 0
});

// 2. Send test
await db.campaigns.sendTest(campaign.id, '[email protected]');

// 3. Review and update
campaign.content = '<h1>Updated Content</h1>';
db.campaigns.save(campaign);

// 4. Launch to all recipients
const result = await db.campaigns.launch(campaign.id);
console.log(`Sent to ${result.recipientCount} people`);

// 5. Check metrics
const updated = db.campaigns.getById(campaign.id);
console.log('Metrics:', updated?.metrics);

​
Best Practices

Always Test First

Send test emails before launching to catch formatting issues

Segment Audiences

Use lists to target specific groups instead of blasting everyone

Monitor Metrics

Track open and click rates to improve future campaigns

Rate Limits

Remember the queue respects SMTP rate limits (80/hour default)

Build docs developers (and LLMs) love

Get started for freeTalk to us