> ## 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.

# Introduction

> Send postcards, manage designs, track deliveries, and manage wallet credits through the Mail API

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

<Warning>
  **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`.
</Warning>

## Base URL

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

## Authentication

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

```bash theme={null}
curl 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](/mail/campaigns/list-campaigns)                      | Create and manage postcard campaigns    |
| [Designs](/mail/designs/list-designs)                            | Create and manage postcard designs      |
| [Wallet](/mail/wallet/get-balance)                               | Manage wallet balance and credits       |
| [Return Addresses](/mail/return-addresses/list-return-addresses) | Manage return addresses                 |
| [Settings](/mail/settings/get-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.

```
/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

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

## Error Responses

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

```json theme={null}
{
  "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                            |