> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.dealmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Campaign

> Create a new mail campaign

Create a new postcard campaign. By default, the campaign is created in `draft` status. Set `launch` to `true` to send immediately.

**Audience:** Provide exactly one audience type: `property_ids`, `contact_ids`, or `list_ids`. Mixing audience types in a single campaign is not supported.

**Design:** Each step can reference an existing `design_id` or provide a `design_prompt` to generate a design on the fly. Since designs are HTML-based, generation is instant — no polling required. The postcard size is determined by the design.

**Credits:** You don't need credits to create a draft. Credits are checked when you launch the campaign (either via `launch: true` or `POST /campaigns/{id}/send`).

<ParamField body="name" type="string" required>
  Campaign name (max 255 characters)
</ParamField>

<ParamField body="description" type="string">
  Campaign description (max 5000 characters)
</ParamField>

<ParamField body="property_ids" type="number[]">
  Property IDs to send to. Mutually exclusive with `contact_ids` and `list_ids`.
</ParamField>

<ParamField body="contact_ids" type="number[]">
  Contact (person) IDs to send to. Mutually exclusive with `property_ids` and `list_ids`.
</ParamField>

<ParamField body="list_ids" type="string[]">
  Saved list IDs to pull audience from. Mutually exclusive with `property_ids` and `contact_ids`.
</ParamField>

<ParamField body="address_to" type="string">
  Who to address mail to: `owner` (mailing address) or `resident` (property address). **Required** when using `property_ids` and for property-based `list_ids`. Not needed for `contact_ids` or people lists.
</ParamField>

<ParamField body="steps" type="object[]" required>
  Mail steps (1-5). Each step needs either a `design_id` or `design_prompt`.

  <Expandable title="Step properties">
    <ParamField body="design_id" type="string">
      Existing design ID to use
    </ParamField>

    <ParamField body="design_prompt" type="string">
      AI prompt to generate an HTML design instantly
    </ParamField>

    <ParamField body="delay_days" type="number" default="0">
      Days to wait after the previous step
    </ParamField>

    <ParamField body="interval_days" type="number" default="0">
      Days between repeated sends
    </ParamField>

    <ParamField body="repeat_count" type="number" default="1">
      Number of times to send this step (1-12)
    </ParamField>

    <ParamField body="skip_if_responded" type="boolean" default="false">
      Skip this step if the recipient has responded
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="contact_name" type="string">
  Your name displayed on the postcard
</ParamField>

<ParamField body="contact_phone" type="string">
  Contact phone number on the postcard
</ParamField>

<ParamField body="contact_email" type="string">
  Contact email on the postcard
</ParamField>

<ParamField body="qr_code_url" type="string">
  URL for the QR code on the postcard
</ParamField>

<ParamField body="return_address_id" type="string">
  ID of a saved return address
</ParamField>

<ParamField body="return_address" type="object">
  Inline return address (alternative to `return_address_id`)

  <Expandable title="Return address properties">
    <ParamField body="name" type="string" required>Name on the return address</ParamField>
    <ParamField body="address_1" type="string" required>Street address</ParamField>
    <ParamField body="address_2" type="string">Apt/Suite/Unit</ParamField>
    <ParamField body="city" type="string" required>City</ParamField>
    <ParamField body="state" type="string" required>Two-letter state code</ParamField>
    <ParamField body="zip" type="string" required>ZIP code</ParamField>
  </Expandable>
</ParamField>

<ParamField body="launch" type="boolean" default="false">
  Launch the campaign immediately after creation. If `false`, the campaign is created in `draft` status and you can launch it later with `POST /campaigns/{id}/send`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.v2.dealmachine.com/v1/mail/campaigns \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Spring Seller Campaign",
      "property_ids": [123456, 789012],
      "address_to": "owner",
      "steps": [{
        "design_id": "design-uuid-123"
      }],
      "contact_name": "John Smith",
      "contact_phone": "555-123-4567",
      "return_address_id": "42",
      "launch": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": 42,
      "name": "Spring Seller Campaign",
      "status": "active",
      "type": "one_off",
      "audience_kind": "properties",
      "property_ids": ["123456", "789012"],
      "contact_ids": [],
      "list_ids": [],
      "total_recipients": 2,
      "total_sent": 0,
      "total_delivered": 0,
      "steps": [{
        "id": "1",
        "step_order": 1,
        "design_id": "design-uuid-123",
        "delay_days": 0,
        "interval_days": 0,
        "repeat_count": 1
      }],
      "created_at": "2026-03-11T14:23:45Z",
      "launched_at": "2026-03-11T14:23:46Z"
    }
  }
  ```
</ResponseExample>