# Docs

- [Introduction](/): Build on LettrLabs — send direct mail programmatically, track attributions and conversions, and react to events in real time.
- [Order of operations](/order-of-operations): The end‑to‑end path to send your first order — find a template, create the order, add recipients, and check out.
- [Creating an Order](/creating-an-order): Generate a direct‑mail order from a template and send it to your recipients.
- [Automations vs. creating an order](/automations-vs-creating-an-order): When to use the app's Automations and when to create orders directly with the API.
- [Attributions and Conversions](/attributions-and-conversions): Record conversions against the mail you send and read them back for reporting.
- [Authentication & API keys](/authentication-api-keys): Generate a public API key in the LettrLabs app and authenticate requests with the X-API-KEY header.
- [MCP server](/mcp): Connect an MCP-compatible AI agent to LettrLabs to draft campaigns, preview pricing, and submit direct mail — from the same chat you're already working in.
- [Inbound webhooks](/inbound-webhooks): Send data to LettrLabs at POST /v1/webhooks/{guid}, with optional HMAC‑SHA256 signature verification and an optional per‑webhook API key.
- [Response shapes and errors](/api-contract): The two response envelopes, how to tell success from failure, and the error cases that do not look like errors.
- [Addresses and deliverability](/addresses): How to supply an address, what validation changes, and how to read the deliverability fields.
- [Pagination](/pagination): Which operations page, how the page cursor is numbered, and why there is no total count.
- [Rate limits and batch sizes](/rate-limits): What the API enforces today, the batch limits that do exist, and how to pace a bulk load.
- [Versioning and change policy](/versioning): What `/v1` means, which changes we make in place, and what would force a new version.
- [API Changelog](/changelog): What changed in the LettrLabs public API — newest first, each entry flagged breaking or non-breaking, with migration notes where action is needed.
- API Reference: Every public LettrLabs API operation, grouped by area, with an interactive request console.
  - [API Reference](/api-reference): Every public LettrLabs API operation, grouped by area, with an interactive request console.
  - Profile
    - [Retrieve the authenticated profile](/api-reference/profile/v1-me-get): Returns profile data for the user authenticated by the supplied API key.
  - Orders
    - [Retrieve order analytics](/api-reference/orders/v1-order-analytics-get): Returns engagement statistics — including per-recipient QR code scans — for the orders named in the Id query parameter (a comma-separated list of order IDs). Orders that cannot be processed are reported per-order with an error status rather than failing the whole request.
    - [List orders](/api-reference/orders/v1-order-get): Returns the account's orders with their status, product, postage, and delivery progress. Supports the id, status, paid, product, postage, and showRecipients filters, plus pageNumber/pageSize pagination.
    - [Preview an order checkout](/api-reference/orders/v1-order-id-checkout-get): Calculates the line-item cost, production, and estimated delivery details for an order so they can be reviewed before checking out. This preview is side-effect-free: it does not modify the order and does not create a payment intent. Calling this endpoint is not required before executing a checkout. Pass `autoBill=false` to preview the checkout under the payment-method opt-out: if the available account balance does not cover the order in full the preview is rejected with HTTP 402 Payment Required and error code INSUFFICIENT_BALANCE — the exact rejection the checkout execute verb returns for the same order — so a preview and an execute agree on whether the order can proceed. The preview remains side-effect-free even when rejected.
    - [Execute an order checkout](/api-reference/orders/v1-order-id-checkout-post): Submits an order for production with the supplied postage type, production speed, and optional hold-until date, and accepts it for payment. Payment settles asynchronously, so a 200 means the checkout was ACCEPTED, not that the order has been charged: the response reports the order's resulting status in "orderStatus", when to start polling in "pollAfterSeconds", and when settlement is expected to have reached a terminal state in "settlementExpectedWithinSeconds" — size your polling from those rather than a bound of your own. On acceptance the order moves to "Payment Needed" immediately and stops being editable: recipient changes, order deletion, and further checkouts return 400 while payment settles. The order then reads "Paid" once settlement completes, or returns to "Draft" if payment fails (retry by checking out again). Never retry a checkout that returned 200 — the charge is already in flight, and a second checkout charges again.
    - [Delete an order](/api-reference/orders/v1-order-id-delete): Deletes an order that has not entered production. Only orders in Draft or Needs Edits status can be deleted; an order in use as an automation template cannot be deleted. Deletion is immediate regardless of the order's size, and the deleted order then behaves exactly like a nonexistent order id on every other operation.
    - [Retrieve an order proof](/api-reference/orders/v1-order-id-proof-get): Renders and returns the order's proof as a PDF document. The proof is generated for the first mailable recipient on the order (the lowest-ID recipient not marked do-not-mail), substituting that recipient's mail-merge fields.
    - [Retrieve a recipient's proof](/api-reference/orders/v1-order-id-proof-recipient-get): Renders and returns a proof PDF for one specific recipient on the order, substituting that recipient's mail-merge fields. The recipient must belong to the order.
    - [Retrieve a recipient's delivery status](/api-reference/orders/v1-order-id-recipient-delivery-status-get): Returns the latest carrier delivery status for one recipient on an order, identified by the recipient's first and last name, or by their address line.
    - [Delete an order's recipients](/api-reference/orders/v1-order-id-recipients-delete): Removes the specified recipients from an order. Pass the IDs of the recipients to remove in the request body. The 200 response reports `requestedRecipients` (distinct ids submitted), `deletedRecipients` (rows actually removed), and `notFoundRecipientIds` (submitted ids that matched no recipient on the order) so a caller holding a stale id can detect a no-op instead of receiving a bare success.
    - [List an order's recipients](/api-reference/orders/v1-order-id-recipients-get): Returns the recipients on an order with their address and mail-merge data. Supports a query filter on recipient name, address, or organization, plus pageNumber/pageSize pagination.
    - [Append recipients to an order](/api-reference/orders/v1-order-id-recipients-put): Adds recipients to an existing order without replacing the ones already on it. Accepts up to 5,000 recipients per request. The order must be editable — status Draft or Edits Needed; once a checkout has been accepted (Paid, Ready For Production, and later statuses) appends are rejected with a 400 invalid-status error, matching the recipient-delete and checkout operations.
    - [Create an order](/api-reference/orders/v1-order-post): Creates a new order from an existing template, copying its design and product settings, and returns the new order's ID. Add recipients and execute checkout separately to send the order.
    - [Retrieve order transactions](/api-reference/orders/v1-order-transaction-get): Returns the financial transactions recorded for the orders named in the Id query parameter (a comma-separated list of order IDs), including transaction type, amounts, and discounts. Orders that cannot be processed are reported per-order with an error status rather than failing the whole request.
  - Templates
    - [List templates](/api-reference/templates/v1-templates-get): Lists the authenticated account's active templates — the set usable as templateId when creating an order. Paginated; preview image URLs are time-limited.
    - [Retrieve a template](/api-reference/templates/v1-templates-id-get): Returns one of the authenticated account's active templates: metadata and preview image URLs only (no design/scene definition).
  - Fonts
    - [List handwriting fonts](/api-reference/fonts/v1-fonts-get): Lists the LettrLabs handwriting fonts available to the authenticated account. Every returned name is accepted by POST /v1/order's handwritingFont field.
  - Conversions
    - [List conversions](/api-reference/conversions/v1-conversions-get): Returns all conversions recorded for the authenticated account, with their processing status.
    - [Delete a conversion](/api-reference/conversions/v1-conversions-id-delete): Marks a conversion for deletion after validating its status. Deletion is asynchronous — check its progress via the conversion status endpoint.
    - [Retrieve a conversion's status](/api-reference/conversions/v1-conversions-id-status-get): Returns the processing status of one conversion by its ID, including whether it has been matched or is pending deletion.
    - [Create conversions](/api-reference/conversions/v1-conversions-post): Submits conversion events for matchback and attribution. Returns validation information and processes the valid records even when some records are invalid. At most 5,000 records per request — a larger batch is rejected in full with a 400 and none of it is processed, so split larger uploads client-side.
  - Automations
    - [List integration orders](/api-reference/automations/v1-integration-orders-get): Returns the account's integration orders (automations) — standing orders that mail each recipient added to them — with their template and configuration details.
    - [Request a proximity mailing](/api-reference/automations/v1-integration-orders-id-by-proximity-post): Finds addresses around a point or address using the supplied filters and queues them as recipients on the integration order. Recipient discovery runs asynchronously after the request is accepted.
    - [Add a recipient to an integration order](/api-reference/automations/v1-integration-orders-id-recipients-post): Adds one recipient to an integration order, validating and standardizing the address before queueing the mail piece for that recipient.
  - Order Recipient Analytics
    - [Record a QR code scan](/api-reference/order-recipient-analytics/v1-order-recipients-statistics-post): Records a QR code scan event against an order recipient, updating that recipient's engagement statistics. Processing is asynchronous — the scan is queued and applied shortly after the request succeeds.
  - Address Book
    - [Create an address book entry](/api-reference/address-book/v1-address-book-post): Adds a recipient to the account's address book, validating and standardizing the supplied address before saving it. This is the canonical path for the address book. The older `/v1/zapierActions/address-book` path is retained for existing integrations and behaves identically.
    - [Add an address book entry](/api-reference/address-book/v1-zapieractions-address-book-post): Adds a recipient to the account's address book, validating and standardizing the supplied address before saving it.