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
Authentication
All Mail endpoints require the same Bearer token as the rest of the API:
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 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.
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:
Mail-Specific Error Codes
