A valid request URL is required to generate request examples{
"campaign": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "draft",
"trigger_kind": "one_shot",
"event_type": "<string>",
"date_attribute": "<string>",
"date_offset_days": 123,
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"frequency_cap_days": 123,
"activated_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"system_key": "<string>",
"system": true,
"claimed": 123,
"steps": [
{
"position": 123,
"template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"offset_hours": 123
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Create a campaign
Requires messaging:manage. It is always created as a draft, and creating one is free on every plan — what a plan gates is arming it. See POST /v1/organization/campaigns/{id}/activate.
segment_id is required and there is no way to express “everybody” other than a segment that matches everybody. A campaign has no filter of its own: an audience defined twice is an audience that can be previewed one way and mailed another, and there would be nothing saying so.
The trigger is a set: trigger_kind plus exactly its own operands. event needs event_type, date_offset needs date_attribute and date_offset_days, and one_shot and segment_entered need neither. Anything else is refused here and by the database.
steps is the sequence, in order, and its position is the array index. A one-shot is a sequence of one. offset_hours on a step is measured from the previous step’s delivery — and from the claim on the first one, which is how “two hours after they sign up” is written without a fifth trigger kind.
A valid request URL is required to generate request examples{
"campaign": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "draft",
"trigger_kind": "one_shot",
"event_type": "<string>",
"date_attribute": "<string>",
"date_offset_days": 123,
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"frequency_cap_days": 123,
"activated_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"system_key": "<string>",
"system": true,
"claimed": 123,
"steps": [
{
"position": 123,
"template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"offset_hours": 123
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Body
Unique per environment. The delivery log records a send by campaign name.
200one_shot, event, segment_entered, date_offset The audience, always. Must belong to the same environment.
The sequence, in order. Replaced as a set on every write.
1 - 10 elementsShow child attributes
Show child attributes
Required on event, refused on the others. One of the published event types — see the Webhooks tag's catalogue.
Required on date_offset. Every one of them is in the past, which is why the offset may not be negative.
created_at, first_seen_at, identified_at, email_verified_at, last_seen_at Required on date_offset.
0 <= x <= 365How long this campaign waits before it may reach the same person again. 0 is no cap of its own; the 24-hour cooldown across all campaigns still applies, and the two are different promises.
0 <= x <= 365Response
The campaign, as a draft.
An audience, a trigger, a sequence and a cap. Per environment, like everything on the customer plane.
Show child attributes
Show child attributes