Create a letter (BILLABLE)
lob_letters_createDestructiveIdempotent
Send a physical letter to a recipient via Lob. Requires confirmation token after preview for production delivery.
Instructions
Commit a letter send. Billable in live mode. Requires a confirmation_token from lob_letters_preview that matches the current payload (live mode only).
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. | |
| file | Yes | Letter body content source (HTML, URL, template ID, or base64 PDF). | |
| color | No | Print in color (true) or black-and-white (false). Affects pricing. | |
| double_sided | No | Print on both sides. Defaults to true for letters. | |
| address_placement | No | Where the recipient address window appears on a letter. | |
| return_envelope | No | Include a return envelope. Boolean true for default, or a return envelope ID. | |
| perforated_page | No | Page number to perforate (used with return_envelope). | |
| custom_envelope | No | Custom envelope reference for letters/checks. | |
| extra_service | No | USPS extra service add-on. Affects pricing and delivery time. | |
| cards | No | Card IDs (`card_…`) to insert. Up to 4. | |
| buckslips | No | Buckslip references to insert. | |
| 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_letters_preview. Required in live mode (LOB_LIVE_MODE=true). |