VX Agents

API directory · Marketing & Analytics

Lob Postcards, Letters & Address Checks

v1.0.0 · 11 endpoints · 0 connections · shared by vx.ai

Send real mail from a chat: check a US address is deliverable with Lob's CASS verification, then print and post a postcard or letter from a saved HTML template, and follow each piece through USPS tracking events to the mailbox.

Connect this API to an AI agent Browse all specs

What you can do with Lob Postcards, Letters & Address Checks via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
POST /us_verifications verifyUsAddress Check and standardise a US address (deliverability, ZIP+4)
GET /addresses listAddresses List saved addresses
POST /addresses createAddress Save an address to reuse as a sender or recipient
GET /addresses/{adr_id} getAddress Get a saved address
GET /templates listTemplates List saved HTML templates for mail pieces
GET /postcards listPostcards List postcards and their delivery status
POST /postcards createPostcard Print and mail a postcard (costs money with a live key)
GET /postcards/{psc_id} getPostcard Get a postcard with its preview and tracking events
GET /letters listLetters List letters and their delivery status
POST /letters createLetter Print and mail a letter (costs money with a live key)
GET /letters/{ltr_id} getLetter Get a letter with its preview and tracking events

Authentication

basicAuth

HTTP Basic

Lob secret API key as the basic-auth username, with an empty password.

How to get a credential

  1. Sign up or sign in at dashboard.lob.com.
  2. Open Settings > API Keys.
  3. Copy the Test secret key (test_...) to try things out, or the Live key (live_...) to send real mail (needs a payment method on the account).
  4. In VX Agents, enter the key as the username and leave the password empty.

Permissions used

Key Operations
Test or live secret key (full account access) verifyUsAddress, listAddresses, getAddress, createAddress, listTemplates, listPostcards, getPostcard, createPostcard, listLetters, getLetter, createLetter

US address verification only returns real results with a live key; test keys return sample data.

Common errors

  • 401 Unauthorized: wrong key, or the key was sent as the password instead of the username.
  • 403 Forbidden: live mail needs a verified account with a payment method, or the feature is not on your plan.
  • 422 Unprocessable Entity: an address field, file/template id or size is invalid; read error.message.
  • 429 Too Many Requests: rate limit (150 requests per 5 seconds per endpoint); back off and retry.

Store the key as a VX Agents credential for this spec; never paste it into chat.

Usage guide

Setup

  • Credential: a Lob secret API key as the basic-auth username with an empty password (Dashboard > Settings > API Keys). Start with the test_ key: test mail is never printed or charged. Switch to the live_ key only when the user is ready to pay for real mail.
  • Worth pinning: a sender address id (adr_..., from createAddress or listAddresses) and the template ids (tmpl_...) the team uses.

Verify an address and mail a postcard or letter

  1. verifyUsAddress with primary_line, city, state, zip_code (or one address string). Check deliverability (deliverable, deliverable_unnecessary_unit, undeliverable, ...) and use the standardised components it returns.
  2. listAddresses / getAddress to reuse a saved sender, or createAddress to save one (name or company, address_line1, address_city, address_state, address_zip).
  3. listTemplates to pick the artwork. front/back (postcards) and file (letters) take a template id, an HTML string, or an HTTPS URL to a PDF/PNG/JPG at the right size.
  4. createPostcard with to (address id or inline address), from, front, back, use_type (marketing or operational) and optional size (4x6, 6x9, 6x11), merge_variables for template fields, send_date to schedule.
  5. createLetter with to, from, file, color (true/false), use_type, and optional double_sided, extra_service (certified, certified_return_receipt, registered; not with usps_standard).
  6. getPostcard / getLetter for the PDF preview url, expected_delivery_date and tracking_events; listPostcards / listLetters for history.

With a live key, createPostcard and createLetter print and post real mail and charge the account: always show the user the recipient, artwork and price tier and get a clear yes first. Send an Idempotency-Key so a retry does not mail twice.

Good to know

  • Ids are prefixed: adr_, psc_, ltr_, tmpl_. metadata takes small string key/value pairs (500 characters in total), useful for your own order or customer id.
  • This spec has no cancel operation; a scheduled piece can only be cancelled in the Lob dashboard before it goes to print, so set send_date when the user may change their mind.
  • merge_variables keys must match the {{variables}} in the template exactly.
  • Rate limit: 150 requests per 5 seconds per endpoint (300 for US verification).
  • Test keys do not really verify addresses: they return fixed answers for special primary_line values.

Source: Lob API reference (https://docs.lob.com/), checked 2026-10-21.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Lob Postcards, Letters & Address Checks” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs