Managing Campaigns via API
Create and manage email campaigns programmatically using the WarmySender API.
Required Scope: campaigns:write (for campaign CRUD), enrollments:write (for enroll/unenroll)
Create an API key with the needed scopes in Settings > API Keys.
Campaign Lifecycle via API:
- Create a campaign (POST /api/v1/campaigns) — always created in draft status
- Review and adjust settings (PATCH /api/v1/campaigns/:id)
- Enroll prospects (POST /api/v1/campaigns/:id/enrollments) — accepts prospectIds, listIds, or emails
- Start the campaign (POST /api/v1/campaigns/:id/start)
- Monitor progress (GET /api/v1/campaigns/:id)
- Pause if needed (POST /api/v1/campaigns/:id/pause)
- Unenroll prospects (DELETE /api/v1/campaigns/:id/enrollments) — remove specific prospects from a running campaign
Creating Prospects with LinkedIn URL:
POST /api/v1/prospects supports a linkedinUrl field for multichannel outreach:
• email (required), firstName, lastName, company, role, phone, linkedinUrl, customFields (object)
• The linkedinUrl field accepts any valid LinkedIn profile URL
• Deduplication is by email — if the email exists, the existing prospect is returned
Creating a Campaign:
POST /api/v1/campaigns requires:
• name — Campaign name (required)
• steps — Array of email steps with subject, bodyHtml, and stepIndex (at least 1 required)
• mailboxIds — Array of connected mailbox IDs to send from (at least 1 required)
• Optional: prospectIds, dailySendLimit, timezone, scheduleDays, trackOpens, trackClicks, stopOnReply, stopOnBounce, startDate, endDate
Key Rules:
- Campaigns are always created in draft status — you must explicitly start them.
- Step 0 always has delayDays=0 (sends immediately). Other steps default to 1 day delay.
- All mailboxes must be connected and have sending enabled.
- Prospects with bounced, unsubscribed, or suppressed status are automatically marked as suppressed in the enrollment.
- The API supports email, linkedin, and multichannel campaigns via the channel field (defaults to email).
Updating a Campaign:
PATCH /api/v1/campaigns/:id — only works on draft or paused campaigns. You can update name, dailySendLimit, sendingWindowStart/End, scheduleDays, tracking settings, and dates.
Starting a Campaign:
POST /api/v1/campaigns/:id/start checks:
• Campaign has at least one step and one mailbox.
• End date (if set) has not passed.
• Your subscription is active.
• If startDate is in the future, campaign is set to 'scheduled' instead of 'running'.
Pausing a Campaign:
POST /api/v1/campaigns/:id/pause — works on running or scheduled campaigns. Sets pausedReason to 'api'.
Enrolling Prospects:
POST /api/v1/campaigns/:id/enrollments — add prospects to a campaign.
• Request body: { prospectIds?: string[], listIds?: string[], emails?: string[] } — pass at least one.
• prospectIds: directly enroll specific prospects by ID.
• listIds: enroll all prospects from one or more prospect lists.
• emails: find and enroll prospects by email address.
• You can combine all three in a single request.
• Requires enrollments:write scope.
Unenrolling Prospects:
DELETE /api/v1/campaigns/:id/enrollments — remove prospects from a campaign.
• Request body: { prospectIds?: string[], emails?: string[] } — pass one or both.
• Response: { data: { unenrolledCount: number, totalProcessed: number } }
• Prospects not currently enrolled are skipped (counted in totalProcessed but not unenrolledCount).
• Use case: unenroll when a prospect replies on another channel (e.g., WhatsApp, LinkedIn) to avoid duplicate outreach.
Idempotency:
The create endpoint supports the Idempotency-Key header for safe retries. Use a unique key per creation request.
Full API Reference: warmysender.com/docs/integrations