Create a campaign

Creates a campaign in the project, a draft: nothing is sent until it is launched. Needs scope write; an admin key may create one in any live project. Writes campaign.created.

Parameters

Name	In	Type	Description
`project_id`required	path	string · uuid	The project’s id
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

application/json · required

CreateCampaignRequest object
list_idsarray of stringrequired

The lists it goes to: 1 to 16 distinct ids of live lists of the project. A recipient on several is sent once, as a subscriber of the first.

1–16 items
namestringrequired

What people call the campaign: 1 to 128 characters, trimmed. Two campaigns may share a name.

example Spring sale
template_idstring · uuidrequired

The template it sends: the id of a message template of the project.
from_emailstring · email | null

example news@acme.example
from_namestring | null

example Acme News
reply_tostring · email | null
subject_overridestring | null

The subject source in place of the template’s.
throttle_per_hourinteger · int64 | null

Most messages an hour, 1 to 4294967295.

1–4294967295
tracking_overrideTrackingOverrideInput | null

What a campaign tracks in place of the project’s settings.tracking.
2 fields
- TrackingOverrideInput object · all fields required
- clicksboolean
  
  Click redirects.
- opensboolean
  
  The open pixel.
transport_overridestring | null

direct or relay:<name> (a relay of the node).

example direct

Responses

201

The campaign, a draft

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.
`Location`	string	The campaign’s URL

Campaign object · all fields required
completed_atstring · date-time | null
created_atstring · date-time
from_emailstring · email | null

null: the project’s settings.from_email.
from_namestring | null

null: the project’s settings.from_name.
idstring · uuid

example 01900000-0000-7000-8000-000000000001
last_errorstring | null

Why the launch failed; null unless failed.
launched_atstring · date-time | null
list_idsarray of string

In the order given.
namestring

example Spring sale
partial_versionsmap of string → integer · int32

The versions of the partials fixed at launch, by name; {} before.
project_idstring · uuid
reply_tostring · email | null

null: the project’s settings.reply_to.
scheduled_atstring · date-time | null

When a scheduled campaign launches; null unless scheduled.
shard_countinteger · int32 | null

Fixed at launch; null before.

≥ 0
statusstring

draft, scheduled, launching, sending, paused, completed, cancelled or failed.

example draft
subject_overridestring | null

null: the template’s subject.
template_idstring · uuid
template_versioninteger · int32 | null

The template’s version fixed at launch; null before.

≥ 0
throttle_per_hourinteger · int32 | null

null: the project’s default_throttle_per_hour, or no limit.

≥ 0
total_recipientsinteger · int64 | null

Recipients of the launch’s snapshot; null before.

≥ 0
tracking_overrideTrackingOverride | null

null: the project’s settings.tracking.
2 fields
- TrackingOverride object · all fields required
- clicksboolean
- opensboolean
transport_overridestring | null

null: the project’s transport, then the node’s default.
updated_atstring · date-time

The latest change: creation, fields, status.

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope write (forbidden)

Problem (application/problem+json)

404

No such project, or another project’s (not_found)

Problem (application/problem+json)

409

The project is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed): unknown_field, required, invalid_type, invalid (also a list or template that is not the project’s, a deleted list, a partial), out_of_range, unknown_relay; or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)