logo
CampaignsCreate campaign

Create campaign

Create a new campaign in draft status. Mailboxes can be assigned using any combination of:

  • mailboxes or mailboxIds - direct mailbox IDs
  • mailboxEmails - resolve mailboxes by email address
  • mailboxTags - all mailboxes matching any of these tags
  • mailboxProvider - all mailboxes with this provider (e.g. "gmail", "outlook")
curl -X POST "https://api.sendkit.ai/v1/campaigns" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
  "name": "Q2 Outbound - Decision Makers",
  "sequence": [
    {
      "type": "email",
      "order": 0,
      "subject": "Quick question about {{companyName}}",
      "body": "<p>Hi {{firstName}},</p><p>I noticed {{companyName}} is scaling fast. Would love to share how we helped similar teams cut outbound costs by 40%.</p>"
    },
    {
      "type": "wait",
      "order": 1,
      "waitDays": 3
    },
    {
      "type": "email",
      "order": 2,
      "subject": "Re: Quick question about {{companyName}}",
      "body": "<p>Hey {{firstName}}, just bumping this up. Happy to send over a case study if that helps.</p>"
    }
  ],
  "schedule": {
    "timezone": "America/Chicago",
    "startTime": "08:30",
    "endTime": "16:00",
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "skipNationalHolidays": true
  },
  "settings": {
    "trackOpens": true,
    "trackClicks": true,
    "includeUnsubscribeLink": false,
    "cc": [
      "sales-log@yourcompany.com"
    ],
    "bcc": [
      "crm-sync@yourcompany.com"
    ],
    "stopOnReply": true,
    "stopOnAutoReply": true,
    "stopOnCompanyReply": true,
    "skipDNC": true,
    "dailySendLimit": 50,
    "emailIntervalMinutes": 12,
    "espMatchingMode": "auto",
    "segCheckMode": "skip_providers",
    "segSkipProviders": [
      "proofpoint",
      "mimecast"
    ],
    "cnameTracking": {
      "enabled": true,
      "domain": "track.yourcompany.com"
    },
    "slackChannelId": "C04ABCDEF12",
    "positiveRepliesOnlySlack": true,
    "webhook": {
      "enabled": true,
      "url": "https://yourcompany.com/webhooks/sendkit",
      "secret": "whsec_abc123xyz",
      "events": [
        "lead.replied",
        "email.sent",
        "lead.bounced"
      ]
    },
    "copyFatigueProtection": {
      "enabled": true,
      "autoRegenerate": true,
      "autoResume": true
    },
    "variantOptimization": {
      "enabled": true,
      "minimumSendsPerVariant": 50,
      "minimumDays": 5,
      "optimizationMetric": "replyRate",
      "keepMinimumVariants": 2
    }
  },
  "mailboxTags": [
    "outreach"
  ]
}'

{
  "success": true,
  "data": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Q1 Outreach Campaign",
    "userId": "664f0a1b2c3d4e5f6a7b8c9d",
    "workspaceId": "664f0a1b2c3d4e5f6a7b8c9e",
    "status": "draft",
    "mailboxes": [
      "665b1c2d3e4f5a6b7c8d9e0f"
    ],
    "sequence": [
      {
        "type": "email",
        "name": "Initial Email",
        "order": 0,
        "subject": "Quick question, {{firstName}}",
        "body": "<p>Hi {{firstName}},</p><p>I noticed {{company}} is growing fast...</p>"
      },
      {
        "type": "wait",
        "name": "Wait 3 days",
        "order": 1,
        "waitDays": 3
      },
      {
        "type": "email",
        "name": "Follow-up",
        "order": 2,
        "subject": "Re: Quick question",
        "body": "<p>Just following up on my last email...</p>"
      }
    ],
    "sendingSchedule": {
      "timezone": "America/New_York",
      "startTime": "09:00",
      "endTime": "17:00",
      "workingDays": [
        1,
        2,
        3,
        4,
        5
      ]
    },
    "trackOpens": true,
    "trackClicks": true,
    "stopOnReply": true,
    "stats": {
      "sent": 0,
      "delivered": 0,
      "opened": 0,
      "clicked": 0,
      "replied": 0,
      "bounced": 0,
      "unsubscribed": 0
    },
    "createdAt": "2025-06-10T10:30:00.000Z",
    "updatedAt": "2025-06-10T10:30:00.000Z"
  }
}
POST
/v1/campaigns
POST
API Key (header: X-Api-Key)
X-Api-Keystring
Required

Platform API key (sk_user_...) or Workspace API key (sk_...)

Platform API key (sk_user_...) or Workspace API key (sk_...)
Content-Typestring
Required

The media type of the request body

Options: application/json
namestring
Required

Campaign name

sequencearray

Email sequence steps

subsequencesarray

Optional list of subsequences (nested follow-up flows). Each subsequence fires when a lead's AI tag matches (trigger.type='ai_tag') or when the lead first replies (trigger.type='reply'). Validation rules (mirrors the dashboard sequence builder): max 15 active (non-archived) subsequences per campaign; at most one active subsequence may have trigger.type='reply'; active ai_tag-trigger values must be unique across subsequences (case-insensitive); the inner sequence follows the same email/wait rules as the main campaign sequence, except the first step MAY be a wait (subsequence emails can be sent as in-thread replies after a delay); trigger is immutable once a subsequence has sent any emails (addedCount > 0 or stats.sent > 0) — archive and recreate to change.

scheduleobject

Sending schedule configuration

settingsobject

Campaign tracking, sending, and deliverability settings

mailboxesarray

Mailbox IDs (legacy field)

mailboxIdsarray

Mailbox IDs to use for sending

mailboxEmailsarray

Resolve mailboxes by email address

mailboxTagsarray

Use all mailboxes matching any of these tags

mailboxProviderstring

Use all mailboxes with this provider

Request Preview
Response
Response will appear here after sending the request


Authentication
header
X-Api-Keystring
Required
API Key for authentication. Platform API key (sk_user_...) or Workspace API key (sk_...)


Body
application/json
namestring
Required
Campaign name
sequencearray
Email sequence steps
subsequencesarray
Optional list of subsequences (nested follow-up flows). Each subsequence
fires when a lead's AI tag matches (trigger.type='ai_tag') or when the
lead first replies (trigger.type='reply').
Validation rules (mirrors the dashboard sequence builder): max 15 active
(non-archived) subsequences per campaign; at most one active subsequence
may have trigger.type='reply'; active ai_tag-trigger values must be
unique across subsequences (case-insensitive); the inner sequence
follows the same email/wait rules as the main campaign sequence, except
the first step MAY be a wait (subsequence emails can be sent as
in-thread replies after a delay); trigger is immutable once a subsequence
has sent any emails (addedCount \\> 0 or stats.sent \\> 0) — archive and
recreate to change.
scheduleobject
Sending schedule configuration
settingsobject
Campaign tracking, sending, and deliverability settings
mailboxesarray
Mailbox IDs (legacy field)
mailboxIdsarray
Mailbox IDs to use for sending
mailboxEmailsarray
Resolve mailboxes by email address
mailboxTagsarray
Use all mailboxes matching any of these tags
mailboxProviderstring
Use all mailboxes with this provider


Responses
 


Was this page helpful?
Last updated 4 days ago
Built with Documentation.AI