Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Create Campaign

Create a new postcard campaign. By default, the campaign is created in draft status. Set launch to true to send immediately.
Audience: Provide one audience type: property_ids, contact_ids, or list_ids. Mixing audience types in a single campaign is not supported.
Save as Ready: Omit property_ids, contact_ids, and list_ids to save the campaign as ready with no properties. Nothing is charged. Add properties later with Add Properties to Campaign; each one starts at step 1 on its own schedule. A Ready campaign always accepts properties. Saving as Ready needs a name that does not start with Draft - and a design_id or design_prompt on every step; otherwise the request returns 400 validation_error and nothing is created. launch: true requires an audience, so sending it without one returns 400 validation_error.
Adding properties later: Set accepts_properties: true on a campaign with an audience to keep adding properties while it is ready, active, or paused, including after you launch it. Without it, the campaign works as it did before: is_accepting_properties is false, properties cannot be added, and the campaign reads ended once its mail is done.
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).
body namestringrequired
Campaign name (max 255 characters)
body descriptionstring
Campaign description (max 5000 characters)
body property_idsnumber[]
Property IDs to send to. Mutually exclusive with contact_ids and list_ids. Omit all three audience fields to save a Ready campaign with no properties.
body contact_idsnumber[]
Contact (person) IDs to send to. Mutually exclusive with property_ids and list_ids.
body list_idsstring[]
Saved list IDs to pull audience from. Mutually exclusive with property_ids and contact_ids.
body address_tostring
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.
body stepsobject[]required
Mail steps (1-5). Each step needs either a design_id or design_prompt.
Step properties
body design_idstring
Existing design ID to use
body design_promptstring
AI prompt to generate an HTML design instantly
body delay_daysnumberdefault: 0
Days to wait after the previous step
body interval_daysnumberdefault: 0
Days between repeated sends
body repeat_countnumberdefault: 1
Number of times to send this step (1-12)
body skip_if_respondedbooleandefault: false
Skip this step if the recipient has responded
body contact_namestring
Your name displayed on the postcard
body contact_phonestring
Contact phone number on the postcard
body contact_emailstring
Contact email on the postcard
body qr_code_urlstring
URL for the QR code on the postcard
body return_address_idstring
ID of a saved return address
body return_addressobject
Inline return address (alternative to return_address_id)
Return address properties
body namestringrequired
Name on the return address
body address_1stringrequired
Street address
body address_2string
Apt/Suite/Unit
body citystringrequired
City
body statestringrequired
Two-letter state code
body zipstringrequired
ZIP code
body accepts_propertiesbooleandefault: false
Keep the campaign open to new properties after it starts, so Add Properties to Campaign can add more while it is ready, active, or paused. Defaults to false when you give an audience. A campaign created without an audience is saved as ready and always accepts properties, so false returns 400 validation_error there.
body launchbooleandefault: false
Launch the campaign immediately after creation. Requires an audience. If false, a campaign with an audience is created in draft status and you can launch it later with POST /campaigns/{id}/send. A campaign without an audience is saved as ready.
When launch is true, campaign creation uses the same guarded sending pipeline as Launch Campaign. A competing or previously claimed launch returns 409 campaign_launch_claimed; inspect the campaign before retrying.
Request example
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",
    "accepts_properties": true,
    "launch": true
  }'
Response example
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": 42,
    "name": "Spring Seller Campaign",
    "status": "active",
    "type": "one_off",
    "is_accepting_properties": true,
    "can_add_properties": true,
    "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"
  }
}
DealMachine API
Powered byHolocron