Creating a draft

One call assembles a whole campaign: pick the channel, describe who it targets, write the copy, and put it on the calendar. What comes back is a draft, ready for a human to review and send from the dashboard.

Nothing on this page arms, schedules or sends anything, and there is no update endpoint to follow it with. Both properties are explained in Campaigns.

Before you start

1. 1

   Get a Product API token with campaign write access

   The endpoint requires the PROJECT_CAMPAIGN_WRITE scope. Scopes are chosen when the token is minted, under Project settings → API tokens — see Authentication.

2. 2

   Know your project UID

   Every call is scoped to one project, which owns the audience, the segments and the senders the campaign will use.

3. 3

   Export credentials

   export INSTASENT_PROJECT="proj_xxx"
   export INSTASENT_TOKEN="eyJhbGciOi..."
   export BASE="https://api.instasent.com/v1/project/$INSTASENT_PROJECT"

The endpoint sits in the medium rate-limit class, and its ceiling scales with the organization's subscription plan — see Rate limits. Campaign creation is a low-frequency operation by nature; if you are anywhere near the ceiling, something is looping.

Your first draft

The smallest useful request is a channel, a title and some copy. Everything else has a default: the audience becomes the whole audience, the sender becomes the project's default for the channel, and the campaign sits on the calendar undated.

curl -X POST "$BASE/campaign" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "title": "Service notice",
    "message": {
      "text": "We are performing maintenance this Sunday. Service may be briefly unavailable."
    }
  }'

A fuller one — a segment, an explicit sender, a date and a tracked link:

{
  "channel": "sms",
  "title": "Summer sale announcement",
  "emoji": "☀️",
  "date": "2026-06-15T09:30:00+02:00",
  "sender": "67bdfa983114d0062d733795",
  "compliance": "opt-out",
  "audience": {
    "include": ["vip-customers"],
    "exclude": ["recently-messaged"]
  },
  "message": {
    "text": "Summer sale starts today: 30% off everything.\nShop now: {{short:https://example.com/sale}}",
    "allowUnicode": false
  }
}

The response

A successful call returns 201 Created with the campaign under entity and, alongside it, anything the platform noticed while building the draft.

{
  "entity": {
    "id": "68b0f2a4e5a6b7c8d9e0f1a2",
    "title": "Summer sale announcement",
    "status": "draft"
  },
  "metadata": {
    "warnings": []
  }
}

entity is the campaign as the campaign read endpoints return it — the example above is trimmed to the fields you are most likely to store. Keep the id: it is what the campaign analytics endpoints take once the campaign has been sent.

Warnings

metadata.warnings reports non-fatal findings. The draft was created; something in it is incomplete and a human has to close the gap before the campaign can go out.

The request body

Only channel and title are required. The shape is deliberately flat: channel decides which of the channel-specific message fields apply, and fields belonging to the other channel are ignored.

Limits

An SMS body has no fixed maximum here — length drives cost instead. See SMS for how characters map to billed parts.

Errors

Validation failures come back as 422 Unprocessable Entity with a stable machine-readable code, so a caller can react to the reason rather than parse a sentence:

{
  "errors": {
    "fields": {
      "errorCode": ["unknown-segment"]
    }
  }
}

Field-level validation errors — a title under 3 characters, a date beyond the one-year horizon — use the same 422 envelope keyed by the field name instead of errorCode:

{
  "errors": {
    "fields": {
      "title": ["This value is too short."]
    }
  }
}

Two conditions produce a 409 Conflict, and in both cases nothing is created. Multi-language campaigns are a paid feature, so a request that declares languages without the subscription to match is refused. And a project that already holds 50 campaigns sitting in draft takes no more: the ceiling is checked before any other work, and it exists so an automated caller cannot fill a project with drafts in a loop. Only the raw draft status counts towards it, so a draft that has been estimated no longer does. Everything else — 401, 403, 429, 5xx — behaves as described in Errors.

What's next