Add contacts
Add researched contacts, each with its own email, to a draft or live campaign.
https://api.rankparse.com/v1/outreach/campaigns/:id/contactsFreeAPI keyStores up to 100 contacts with their subject and body. Works on a draft, a campaign ready for review, and a launched campaign (a top-up). Nothing is sent: added emails wait until the campaign is launched and, for agents, reviewed. Contacts that break a rule are not added and come back in skipped.
Path parameters
idstringrequiredThe campaign id. Its status must be draft, ready_to_review or pushed, otherwise 409 campaign_not_editable (for example while a launch is running).
Body parameters
contactsarray of objectsrequired1 to 100 contacts. An empty or missing array returns 400 no_contacts; more than 100 returns 400 too_many_contacts. The campaign holds at most 500, so a batch over the remaining room keeps its first valid contacts and skips the rest as campaign_full.
Show propertiesHide properties
emailstringrequiredA researched, real address. Lowercased. Must look like name@domain.tld, otherwise skipped as invalid_email.
domainstringrequiredThe prospect's domain. Lowercased, with http(s)://, www. and paths removed. Internationalized domains must be in punycode (xn--) form. Otherwise skipped as invalid_domain.
subjectstringrequiredTrimmed. Up to 500 characters.
bodystringrequiredPlain text, trimmed. Up to 10,000 characters.
namestringContact name, trimmed and cut to 200 characters.
domain_authoritynumberOptional, from Domain Authority. Rounded; values outside 0 to 100 are stored as unknown instead of rejecting the contact.
Response
addedintegerContacts added by this call.
total_contactsintegerContacts in the campaign after this call.
skippedarrayOne { "email", "reason" } per contact that was not added. Reasons: invalid_email, invalid_domain, missing_copy (subject or body empty), copy_too_long, duplicate_email, duplicate_domain (already in this campaign or earlier in the batch), campaign_full, already_contacted (you emailed this address from an earlier campaign).
next_stepstringOnly when contacts were added to a launched campaign: a reminder that the new emails do nothing until you launch again (and, for an agent, that they then wait for the user's review).
Behavior
- A contact already in the campaign is skipped and its copy is not changed. To rewrite emails that are in the campaign, use Update contacts instead of creating a second campaign.
- Contacts are matched case-insensitively by email and by domain.
- Adding contacts to a launched campaign keeps it
pushed.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_json | The body is not valid JSON. |
| 400 | no_contacts | contacts is missing or empty. |
| 400 | too_many_contacts | More than 100 contacts in one call. |
| 403 | capability_missing | Your role cannot manage outreach. |
| 404 | campaign_not_found | Not in your workspace, or archived. |
| 409 | campaign_not_editable | The campaign is mid-launch or in a state that cannot take contacts. Retry shortly. |
Plus the shared errors.
Related
MCP tool: outreach_add_contacts (accepts campaign_id, contacts).