Create a campaign

POST/v1/campaigns

Secret key — sk_… or sk_test_… · Base URL https://api.volanea.com

Created in draft. Audience is everyone (all), a segment (segment + segmentId), or ad-hoc conditions (filter).

Body

Required · application/json

namestringrequired
subjectstringrequired
previewTextstring | null
Preheader — the preview line after the subject in the inbox. Supports `{{variable}}` placeholders.
bodystringrequired
HTML with `{{variable}}` placeholders.
bodyBlocksstring | array | object | null
Optional design the visual editor compiled `body` from — a JSON string of the GrapesJS project (or a legacy block array/object). Stored verbatim and never sent.
fromEmailemailrequired
fromNamestring
replyTostring | null
Sets the Reply-To header on every send.
audienceenum
allsegmentfilter
segmentIdstring
Required when `audience` is `"segment"`.
filterobject
Nested condition tree evaluated against contacts, their custom `data`, and their activity.
- logicenumrequired
  andor
- groupsobject[]required
  - filtersobject[]required
abSubjectBstring
Subject-line B for an A/B experiment; the winner is auto-sent to the remainder.
abSamplePctinteger
Percent of the audience used for the A/B sample (default 20).

Response

201 · Campaign

campaignIdstringrequired
projectIdstring
namestringrequired
subjectstringrequired
previewTextstring | null
Preheader — the preview line inboxes show after the subject. Injected as a hidden block at the top of the body at send time.
bodystringrequired
bodyBlocksstring | array | object | null
The visual editor's design `body` was compiled from — a JSON string of the GrapesJS project (or a legacy block array/object), stored so the editor can reopen it. Ignored when sending — only `body` is delivered.
fromNamestring | null
fromEmailemailrequired
replyTostring | null
Becomes the Reply-To header when set.
statusenumrequired
draftscheduledsendingsentcancelled
audienceenumrequired
allsegmentfilter
segmentIdstring | null
filterobject | null
abSubjectBstring | null
abSamplePctinteger | null
abDecideAtstring | null
abWinnerenum
abnull
scheduledForstring | null
sentAtstring | null
totalRecipientsinteger
deliveredinteger
openedinteger
clickedinteger
bouncedinteger
complainedinteger
unsubscribedinteger
createdAtdate-timerequired

Errors

Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.

401Missing or invalid API key.
404Not found.
422Request validation failed (code `validation_error`, 422).

Request

curl https://api.volanea.com/v1/campaigns \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "subject": "Your order shipped",
    "body": "<p>On its way, {{firstName}}.</p>",
    "fromEmail": "hello@yourdomain.com",
    "previewText": "<previewText>",
    "bodyBlocks": "<bodyBlocks>"
  }'

Response

201 · application/json

{
  "success": true,
  "data": {
    "campaignId": "cmp_2b8e",
    "projectId": "<projectId>",
    "name": "Welcome",
    "subject": "Your order shipped",
    "previewText": "<previewText>",
    "body": "<p>On its way, {{firstName}}.</p>",
    "bodyBlocks": "<bodyBlocks>",
    "fromName": "Acme",
    "fromEmail": "hello@yourdomain.com",
    "replyTo": "support@yourdomain.com",
    "status": "draft",
    "audience": "all",
    "segmentId": "seg_4a71",
    "filter": {
      "logic": "and",
      "groups": [
        {
          "filters": null
        }
      ]
    },
    "abSubjectB": "<abSubjectB>",
    "abSamplePct": 1,
    "abDecideAt": "2026-01-01T09:00:00.000Z",
    "abWinner": "a",
    "scheduledFor": "2026-01-01T09:00:00Z",
    "sentAt": "2026-01-01T09:00:00.000Z",
    "totalRecipients": 1,
    "delivered": 1,
    "opened": 1,
    "clicked": 1,
    "bounced": 1,
    "complained": 1,
    "unsubscribed": 1,
    "createdAt": "2026-01-01T09:00:00.000Z"
  }
}

92 endpoints · OpenAPI document