launch_campaign

Arguments

• object
• campaign_idstring · uuidrequired

  The campaign’s id: a draft, or a campaign left launching by an interrupted launch.

• confirmboolean

  true launches the campaign. Without it the call checks what the launch checks, answers the preflight and changes nothing.

  default false

• project_idstring · uuid | null

  The campaign’s project. An admin key must pass it; a project key’s own project is used and this is ignored.

No other arguments are accepted.

Result

The result comes back as structuredContent, with the same JSON as a text block.

• object · all fields required
• campaignCampaign

  The campaign after the call, as get_campaign returns it: the launch’s answer (POST /api/v1/projects/{project_id}/campaigns/{campaign_id}/launch) when confirmed; unchanged by a dry run.

  23 fields

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

    null: the project’s settings.from_email.

  • from_namestring | null

    null: the project’s settings.from_name.

  • idstring · uuid
  • last_errorstring | null

    Why the launch failed; null unless failed.

  • launched_atstring · date-time | null
  • list_idsarray of string

    The lists it goes to, in the order given.

  • namestring
  • partial_versionsmap of string → integer · uint32

    The versions of the partials fixed at launch, by name; {} before.

  • project_idstring · uuid
  • reply_tostring | null

    null: the project’s settings.reply_to.

  • scheduled_atstring · date-time | null

    When a scheduled campaign launches; null unless scheduled.

  • shard_countinteger · uint32 | null

    Fixed at launch; null before.

    ≥ 0

  • statusstring

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

  • subject_overridestring | null

    null: the template’s subject.

  • template_idstring · uuid
  • template_versioninteger · uint32 | null

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

    ≥ 0

  • throttle_per_hourinteger · uint32 | null

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

    ≥ 0

  • total_recipientsinteger · uint64 | 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.

• effectstring

  The outcome in words, for the agent and its user.

• outcomeLaunchOutcome

  What a launch did.

  would_launch A dry run of a draft that meets every precondition: nothing changed; a call with confirm: true launches it.

  would_resume A dry run of a campaign whose launch was interrupted (launching): a call with confirm: true finishes it.

  launched Launched: its deliveries are queued; it is sending.

  failed The launch found no recipient by the time it wrote them: the campaign is failed, last_error says why.

• preflightCampaignPreflight | null

  What preflight_campaign answers for the draft: in a dry run of a draft; null otherwise.

  8 fields

  • CampaignPreflight object · all fields required
  • campaign_idstring · uuid
  • domainCampaignPreflightDomain | null

    The project’s sending domain of the sender; null when it has none.

    4 fields

    • CampaignPreflightDomain object · all fields required
    • domainstring
    • idstring · uuid
    • statusstring

      pending, verified or failed; only a verified one sends.

    • warningsarray of CampaignPreflightWarning

      Checks that do not decide the status and are not ok (ptr, tracking_tls): the launch goes ahead, delivery may suffer.

      3 fields

      • CampaignPreflightWarning object · all fields required
      • checkstring
      • detailstring | null
      • statusstring

        missing, mismatch or warning.

  • estimated_duration_secsinteger · uint64 | null

    How long sending takes at throttle_per_hour, in seconds; null without a limit or a count.

    ≥ 0

  • from_emailstring | null

    The sender: the campaign’s, else the project’s settings.from_email; null when neither names one.

  • recipientsinteger · uint64 | null

    Recipients after deduplication and suppression: the deliveries the launch would write. null when a list is missing or deleted.

    ≥ 0

  • throttle_per_hourinteger · uint32 | null

    Most messages an hour: the campaign’s, else the project’s default_throttle_per_hour; null: no limit.

    ≥ 0

  • transportstring

    The transport the messages go through: direct or relay:<name>.

  • violationsarray of Violation

    Every unmet precondition of the launch, as a precondition_failed error would list them; empty: it can be launched.

    3 fields

    • Violation object · all fields required
    • codestring

      What is wrong, snake_case.

    • fieldstring

      The field it is about (from_email, list_ids.0, transport).

    • messagestring

Definitions

Errors

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors

HTTP API

The same operation over HTTP: POST /api/v1/projects/{project_id}/campaigns/{campaign_id}/launch