---
title: "POST /v1/launch_campaign"
method: POST
path: "/v1/launch_campaign"
tags: ["GTM verbs"]
---

# POST /v1/launch_campaign

`POST /v1/launch_campaign`

## Request

- Base URL: `https://api.layrcake.dev`
- URL: `https://api.layrcake.dev/v1/launch_campaign`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `campaign_id` string, uuid, required
  - `confirmation_token` string
  - `daily_send_limit` integer
  - `dry_run` boolean
  - `supersedes` string, uuid: The confirmation_token of the approval this request replaces. Needed only when that approval was already approved and hasn't started yet; one still waiting for a decision is replaced automatically. Only where Layrcake runs approved actions itself (the result's approval block says execution: server); anywhere else it is refused. A dry run doesn't check it, so it refuses it: send it on the call itself.
  - `first_send_not_before` string, date-time: The earliest the first emails may go out (ISO 8601). They start at the first sending-window opening at least 60 minutes after a person approves, and not before this time. It can't be later than the approval's lifetime after this request (7 days by default); a later time is refused. Only where Layrcake runs approved actions itself (the result's approval block says execution: server); anywhere else it is refused. A dry run doesn't check it, so it refuses it: send it on the call itself.

## Response `200`

Successful outcome

- union
  - object
    - `result` union, required
      - object
        - `expected_start` object
          - `days` integer, nullable, required
          - `estimated` true, required
          - `label` string, required
        - `status` 'needs_confirmation' | 'launched', required
        - `campaign_id` string, required
        - `confirmation_token` string
        - `mailboxes_attached` integer
        - `leads_active` integer
        - `leads_suppressed_at_launch` integer
        - `removed` object
          - `opted_out` integer, required
          - `do_not_contact` integer
          - `no_location` integer
          - `excluded` integer
          - `invalid` integer, required
          - `platform_blocked` integer, required
          - `contacted_recently` integer
          - `capped` integer, required
          - `other` integer, required
          - `total` integer, required
        - `daily_send_limit` integer
        - `approval_email` 'queued' | 'reused' | 'suppressed_rate_limit' | 'no_approver'
        - `approval` object
          - `id` string, uuid, required
          - `state` 'draft' | 'pending_approval' | 'held' | 'approved' | 'queued' | 'executing' | 'declined' | 'expired' | 'superseded' | 'cancelled' | 'failed' | 'completed' | 'execution_failed', required
          - `execution` 'server' | 'agent_retry', required
          - `campaign` object
            - `state` string, required
            - `held` boolean, required
            - `share` integer, nullable, required
          - `state_reason` 'waiting_for_capacity' | 'waiting_for_history', nullable
          - `audience_names` string[], required
          - `expires_at` string, required
          - `first_send_at` string, nullable, required
          - `note` string, nullable, required
          - `operation_id` string, uuid, nullable, required
          - `superseded_by` string, uuid, nullable, required
          - `instance` integer, required
          - `asked_again_after` object, nullable, required
            - `id` string, uuid, required
            - `state` 'draft' | 'pending_approval' | 'held' | 'approved' | 'queued' | 'executing' | 'declined' | 'expired' | 'superseded' | 'cancelled' | 'failed' | 'completed' | 'execution_failed', required
          - `reused` boolean, required
      - object
        - `dry_run` true, required
        - `advisory` true, required
        - `evaluated_at` string, required
        - `plan` object, required
          - `verb` 'launch_campaign', required
          - `plan_version` 3, required
          - `input_version` string, required
          - `credits_estimate` string, required
          - `would_exceed` string[], required
          - `warnings` string[], required
          - `would` object, required
            - `mailboxes_attached` integer, required
            - `leads_active` integer, required
            - `leads_suppressed_at_launch` integer, required
            - `removed` object, required
              - …
            - `daily_send_limit` integer, required
            - `needs_confirmation` true, required
  - object
    - `result` union, required
      - object
        - `expected_start` object
          - `days` integer, nullable, required
          - `estimated` true, required
          - `label` string, required
        - `status` 'needs_confirmation' | 'launched', required
        - `campaign_id` string, required
        - `confirmation_token` string
        - `mailboxes_attached` integer
        - `leads_active` integer
        - `leads_suppressed_at_launch` integer
        - `removed` object
          - `opted_out` integer, required
          - `do_not_contact` integer
          - `no_location` integer
          - `excluded` integer
          - `invalid` integer, required
          - `platform_blocked` integer, required
          - `contacted_recently` integer
          - `capped` integer, required
          - `other` integer, required
          - `total` integer, required
        - `daily_send_limit` integer
        - `approval_email` 'queued' | 'reused' | 'suppressed_rate_limit' | 'no_approver'
        - `approval` object
          - `id` string, uuid, required
          - `state` 'draft' | 'pending_approval' | 'held' | 'approved' | 'queued' | 'executing' | 'declined' | 'expired' | 'superseded' | 'cancelled' | 'failed' | 'completed' | 'execution_failed', required
          - `execution` 'server' | 'agent_retry', required
          - `campaign` object
            - `state` string, required
            - `held` boolean, required
            - `share` integer, nullable, required
          - `state_reason` 'waiting_for_capacity' | 'waiting_for_history', nullable
          - `audience_names` string[], required
          - `expires_at` string, required
          - `first_send_at` string, nullable, required
          - `note` string, nullable, required
          - `operation_id` string, uuid, nullable, required
          - `superseded_by` string, uuid, nullable, required
          - `instance` integer, required
          - `asked_again_after` object, nullable, required
            - `id` string, uuid, required
            - `state` 'draft' | 'pending_approval' | 'held' | 'approved' | 'queued' | 'executing' | 'declined' | 'expired' | 'superseded' | 'cancelled' | 'failed' | 'completed' | 'execution_failed', required
          - `reused` boolean, required
      - object
        - `dry_run` true, required
        - `advisory` true, required
        - `evaluated_at` string, required
        - `plan` object, required
          - `verb` 'launch_campaign', required
          - `plan_version` 3, required
          - `input_version` string, required
          - `credits_estimate` string, required
          - `would_exceed` string[], required
          - `warnings` string[], required
          - `would` object, required
            - `mailboxes_attached` integer, required
            - `leads_active` integer, required
            - `leads_suppressed_at_launch` integer, required
            - `removed` object, required
              - …
            - `daily_send_limit` integer, required
            - `needs_confirmation` true, required
    - `layrcake` object, required
      - `request_id` string, uuid, required
      - `credits_charged` string, required
      - `credits_available` string, required
      - `replayed` boolean
      - `route` object
        - `used` 'balanced' | 'cheapest' | 'broadest' | 'fastest', required
        - `source` 'request' | 'key' | 'guess' | 'default', required

## Other responses

- `202`: Accepted, in one of two shapes. With `approval`: a person approved it, and Layrcake runs it itself (`approved` until its start, then `in_progress`); calling again with the token only reads this status. With `request_id`: the first call with this Idempotency-Key is still running; read it with get_request.
- `4XX`: Caller, scope, confirmation, or credit error
- `5XX`: Provider or service error

---

[API](https://skmtc.dev/layrcake/apis/layrcake-api.md) · [All operations](https://skmtc.dev/layrcake/apis/layrcake-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layrcake/apis/layrcake-api/revisions/24c80e33c274?raw)