Create a postcard (BILLABLE)
lob_postcards_createDestructiveIdempotent
Create and send a physical postcard via Lob API. Provide to, from, front, and back; requires confirmation token in live mode.
Instructions
Commit a postcard send. Billable in live mode: produces real physical mail and is charged to your Lob account. In live mode, requires a confirmation_token from lob_postcards_preview that matches the current payload. In test mode, the token is optional (dev ergonomics).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | No | Internal description (max 255 chars). | |
| to | Yes | Recipient address. Either a saved address ID (`adr_…`) or an inline address. | |
| from | Yes | Sender (return) address. Either a saved address ID (`adr_…`) or an inline address. | |
| send_date | No | ISO 8601 timestamp (e.g. '2026-05-01T00:00:00Z') to schedule the send. Must be at most 180 days in the future. | |
| mail_type | No | Mail class. Defaults to usps_first_class for most pieces. | |
| merge_variables | No | Key/value pairs substituted into Handlebars-style {{variables}} in your HTML/template content. | |
| metadata | No | Up to 20 string key/value pairs to attach to the resource. | |
| billing_group_id | No | Billing group ID (`bg_…`) to attribute the charge to. | |
| use_type | No | Required for some mail classes. 'marketing' for promotional, 'operational' for transactional. | |
| front | Yes | Front-of-postcard content source. | |
| back | Yes | Back-of-postcard content source. | |
| size | No | Postcard size. Defaults to 4x6. | |
| idempotency_key | No | Idempotency key (max 256 chars). If omitted, the server auto-generates a value derived from the confirmation_token when present, otherwise a fresh UUIDv4. Lob deduplicates identical keys for 24 hours. | |
| extra | No | Additional Lob API parameters not enumerated above. Merged into the request body verbatim. See https://docs.lob.com for the full parameter list per resource. | |
| confirmation_token | No | Token from lob_postcards_preview. Required in live mode (LOB_LIVE_MODE=true). |