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 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).
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.
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 launchbooleandefault: 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.
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",
    "launch": true
  }'
Response example
{
  "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"
  }
}
DealMachine API
Powered byHolocron