Apollo Core Workflow B: Email Sequences & Outreach
Overview
Build Apollo.io email sequencing and outreach automation via the REST API. Sequences in Apollo are called "emailer_campaigns" in the API. This covers listing, searching, adding contacts, tracking engagement, and managing sequence lifecycle. All endpoints require a master API key.
Prerequisites
- Completed
apollo-core-workflow-a (lead search)
- Apollo account with Sequences feature enabled
- Connected email account in Apollo (Settings > Channels > Email)
- Master API key (not standard)
Instructions
Step 1: Search for Existing Sequences
import axios from 'axios';
const client = axios.create({
baseURL: 'https://api.apollo.io/api/v1',
headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.APOLLO_API_KEY! },
});
export async function searchSequences(query?: string) {
const { data } = await client.post('/emailer_campaigns/search', {
q_name: query,
page: 1,
per_page: 25,
});
return data.emailer_campaigns.map((seq: any) => ({
id: seq.id,
name: seq.name,
active: seq.active,
numSteps: seq.num_steps ?? seq.emailer_steps?.length ?? 0,
stats: {
totalContacts: seq.unique_scheduled ?? 0,
delivered: seq.unique_delivered ?? 0,
opened: seq.unique_opened ?? 0,
replied: seq.unique_replied ?? 0,
bounced: seq.unique_bounced ?? 0,
},
createdAt: seq.created_at,
}));
}
Step 2: Get Email Accounts for Sending
Before adding contacts to a sequence, you need the email account ID that will send the messages.
export async function getEmailAccounts() {
const { data } = await client.get('/email_accounts');
return data.email_accounts.map((acct: any) => ({
id: acct.id,
email: acct.email,
sendingEnabled: acct.active,
provider: acct.type,
dailySendLimit: acct.daily_email_limit,
}));
}
Step 3: Add Contacts to a Sequence
The add_contact_ids endpoint enrolls contacts into an existing sequence. You must specify which email account sends the messages.
export async function addContactsToSequence(
sequenceId: string,
contactIds: string[],
emailAccountId: string,
) {
const { data } = await client.post(
`/emailer_campaigns/${sequenceId}/add_contact_ids`,
{
contact_ids: contactIds,
emailer_campaign_id: sequenceId,
send_email_from_email_account_id: emailAccountId,
sequence_active_in_other_campaigns: false,
},
);
return {
added: data.contacts?.length ?? 0,
alreadyInCampaign: data.contacts_already_in_campaign ?? 0,
errors: data.not_added_contact_ids ?? [],
};
}
Step 4: Update Contact Status in a Sequence
export async function removeContactsFromSequence(
sequenceId: string,
contactIds: string[],
action: 'finished' | 'removed' = 'finished',
) {
const { data } = await client.post('/emailer_campaigns/remove_or_stop_contact_ids', {
emailer_campaign_id: sequenceId,
contact_ids: contactIds,
});
return {
updated: data.contacts?.length ?? 0,
};
}
Step 5: Create and Manage Contacts for Sequences
Contacts must exist in your Apollo CRM before adding to sequences. Use the Contacts API to create them.
export async function createContact(params: {
firstName: string;
lastName: string;
email: string;
title?: string;
organizationName?: string;
websiteUrl?: string;
}) {
const { data } = await client.post('/contacts', {
first_name: params.firstName,
last_name: params.lastName,
email: params.email,
title: params.title,
organization_name: params.organizationName,
website_url: params.websiteUrl,
});
return {
id: data.contact.id,
email: data.contact.email,
name: `${data.contact.first_name} ${data.contact.last_name}`,
};
}
export async function searchCrmContacts(query: string) {
const { data } = await client.post(, {
: query,
: ,
: ,
});
data..( ({
: c.,
: c.,
: c.,
: c.,
: c.,
}));
}
Step 6: Full Outreach Pipeline
async function launchOutreach(
sequenceId: string,
leads: Array<{ firstName: string; lastName: string; email: string; title?: string; company?: string }>,
) {
const accounts = await getEmailAccounts();
const sender = accounts.find((a: any) => a.sendingEnabled);
if (!sender) throw new Error('No active email account found');
const contactIds: string[] = [];
for (const lead of leads) {
try {
const contact = await createContact({
firstName: lead.firstName,
lastName: lead.lastName,
email: lead.email,
title: lead.title,
organizationName: lead.company,
});
contactIds.push(contact.);
} (: ) {
existing = (lead.);
(existing. > ) contactIds.(existing[].);
}
}
result = (sequenceId, contactIds, sender.);
.();
result;
}
Output
- Sequence search via
POST /emailer_campaigns/search
- Email account listing via
GET /email_accounts
- Contact enrollment via
POST /emailer_campaigns/{id}/add_contact_ids
- Contact removal via
POST /emailer_campaigns/remove_or_stop_contact_ids
- Contact creation via
POST /contacts and search via POST /contacts/search
- Full outreach pipeline: create contacts, find sender, enroll in sequence
Error Handling
| Error | Cause | Solution |
|---|
| 403 Forbidden | Standard API key used | Sequence endpoints require a master API key |
| No email accounts | Inbox not connected | Connect email at Settings > Channels > Email in Apollo UI |
| Contact already enrolled | Duplicate enrollment | Check contacts_already_in_campaign in response |
| Contact not found | ID does not exist in CRM | Create via POST /contacts first |
Resources
Next Steps
Proceed to apollo-common-errors for error handling patterns.
