Skip to main content

​
POST /campaigns

Create a new campaign targeting a contact book.

​
Authentication

JWT Bearer token (dashboard auth)

​
Request Body

FieldTypeRequiredDescription
namestringYesCampaign name
fromstringYesFrom email address (must be a verified domain)
subjectstringYesEmail subject line
contactBookIdstringYesUUID of the target contact book
previewTextstringNoPreview text shown in email clients
htmlstringNoHTML email content
textstringNoPlain text content
replyTostring or string[]NoReply-to address(es)
ccstring or string[]NoCC address(es)
bccstring or string[]NoBCC address(es)
sendNowbooleanNoSchedule immediately on creation
scheduledAtstringNoISO 8601 datetime to schedule for
batchSizenumberNoEmails per batch (1-100000, default 100)

​
Response

{
  "success": true,
  "data": {
    "campaign": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "March Newsletter",
      "status": "draft",
      "from_email": "news@yourdomain.com",
      "subject": "What's new in March",
      "total_contacts": 1500,
      "created_at": "2026-03-08T12:00:00Z"
    }
  }
}

​
Example

curl -X POST https://app.usesendi.com/api/campaigns \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March Newsletter",
    "from": "news@yourdomain.com",
    "subject": "What'\''s new in March",
    "contactBookId": "660e8400-e29b-41d4-a716-446655440000",
    "previewText": "Big updates this month...",
    "html": "<h1>Hello {{first_name}}</h1><p>Here are the updates...</p>",
    "sendNow": true
  }'

​
Errors

StatusErrorCause
400Invalid request dataMissing required fields
403Campaign limit reachedFree plan allows 1 active campaign
404Contact book not foundInvalid or unauthorized contact book ID