Introduction

The Mail API lets you send physical postcards to properties programmatically — create campaigns, generate designs from prompts, track delivery analytics, and manage wallet credits.

Mail API must be enabled. All endpoints under /v1/mail require the Mail app API access to be enabled for your organization. Enable it in Settings > Mail > API Access before making requests. If not enabled, all endpoints return a 403 with error code mail_not_enabled.

Base URL

1https://api.v2.dealmachine.com/v1/mail

Authentication

All Mail endpoints require the same Bearer token as the rest of the API:

12curl https://api.v2.dealmachine.com/v1/mail/campaigns \
  -H "Authorization: Bearer dm_sk_live_xxx"

Key Differences from Other Mailing APIs

Instant Design Generation

Designs are HTML-based, so generation from prompts is instant — no polling required. When you create a design with a prompt, the generated HTML is returned immediately in the response.

Flexible Audience Targeting

Target recipients using exactly one audience type per campaign: property_ids, contact_ids, or list_ids. Recipients are automatically derived from property owner data or saved list contents. This integrates with your existing DealMachine property intelligence.

Wallet Credits

Sending mail requires wallet credits. Check your balance with GET /wallet/balance and add funds with POST /wallet/add-funds. Credits are charged when postcards are sent, not when campaigns are created. The API returns 402 if you attempt to launch a campaign without sufficient credits.

Resources

Resource	Description
Campaigns	Create and manage postcard campaigns
Designs	Create and manage postcard designs
Wallet	Manage wallet balance and credits
Return Addresses	Manage return addresses
Settings	Manage organization-level mail defaults

Resource Hierarchy

Campaigns are the top-level resource. Designs, wallet, return addresses, and settings are independent resources used by campaigns. Settings hold the organization-level defaults (postcard size, sender name, contact frequency limit, QR code URL, signature image) that pre-populate new campaigns.

1234567891011121314/v1/mail/campaigns
/v1/mail/campaigns/{id}/send
/v1/mail/campaigns/{id}/pause
/v1/mail/campaigns/{id}/resume
/v1/mail/campaigns/{id}/recipients
/v1/mail/campaigns/{id}/analytics
/v1/mail/campaigns/{id}/cost-estimate
/v1/mail/designs
/v1/mail/wallet/balance
/v1/mail/wallet/add-funds
/v1/mail/wallet/transactions
/v1/mail/wallet/pricing
/v1/mail/return-addresses
/v1/mail/settings

Workflow

Create a design — provide HTML or a prompt for instant AI generation
Create a campaign — select audience (property IDs, contact IDs, or lists), assign design, set return address
Check cost — verify wallet balance covers the campaign
Launch — POST /campaigns/{id}/send starts the sending pipeline
Monitor — track delivery status via analytics endpoint

Error Responses

Mail endpoints use the same error format as the rest of the API:

1234567{
  "error": {
    "code": "mail_not_enabled",
    "message": "Mail API is not enabled for this organization. Enable it in Settings > Mail > API Access.",
    "request_id": "req_abc123def456"
  }
}

Mail-Specific Error Codes

Code	Status	Description
`mail_not_enabled`	403	Mail API is not enabled for this organization
`campaign_not_found`	404	Campaign does not exist or does not belong to your organization
`design_not_found`	404	Design does not exist
`return_address_not_found`	404	Return address does not exist
`insufficient_credits`	402	Wallet does not have enough credits
`purchase_limit_exceeded`	402	Daily/hourly purchase limit exceeded