STACK
MENU
DOCS / THE ACCOUNT / LETTERS AND POSTCARDS

Letters and postcards

How an agent checks a mailing address, sends a printed letter or postcard and follows it to the door. What the service is and what it costs is on Services.

Before you start

  • The account needs an active street address, which is the return address. See Street address.
  • The account needs credit. The price is held when the letter is sent and charged at cost.

Check an address

prompt
Check whether 1 Main St, Reno NV 89501 is a deliverable address.

The client calls stack_check_mailing_address and returns deliverable or undeliverable with the standardised address. From code: stack.post.checkAddress('acct_123', address, { passportToken }). A check is one action.

Send a letter

prompt
Send a letter from the assistant account to Anna Berg, 1 Main St, Reno NV 89501, confirming her order.

The client calls stack_send_letter. From code or the terminal:

typescript
const letter = await stack.post.send('acct_123', {
  to: { name: 'Anna Berg', line1: '1 Main St', city: 'Reno', state: 'NV', postal_code: '89501' },
  sender_name: 'Acme Ops',
  use_type: 'operational',
  content: { text: 'Your order is confirmed.' },
}, { passportToken });
// letter.id, letter.state, letter.held_cents
bash
npx @getstackrun/cli post acct_123 send --use-type operational --sender-name "Acme Ops" \
  --to-name "Anna Berg" --to-line1 "1 Main St" --to-city Reno --to-state NV --to-postal-code 89501 \
  --text "Your order is confirmed."
  • use_type is required: operational or marketing.
  • sender_name is required, at most 40 characters.
  • content is text, or a PDF as pdf_base64 (--pdf-file in the terminal).
  • Text is at most 20,000 characters and a PDF at most 4 MB.
  • The most pages depends on the provider the letter goes through. Through Lob: 60 pages single-sided or 120 double-sided inside the US, and 6 or 12 outside it. Through PostGrid: 20. A letter over the limit is refused, and the refusal names the limit.
  • Options: color, double_sided (on unless set to false), mail_class (first_class or standard) and extra_service (certified or certified_return_receipt). Certified post goes first class only.
  • The recipient can be outside the US.
  • One letter is one action. A refused letter is not charged.

Send a postcard

typescript
await stack.post.send('acct_123', {
  kind: 'postcard',
  to: { name: 'Anna Berg', line1: '1 Main St', city: 'Reno', state: 'NV', postal_code: '89501' },
  sender_name: 'Acme',
  use_type: 'marketing',
  front: { text: 'Hello' },
  back: { text: 'See you soon' },
}, { passportToken });

The tool is stack_send_postcard. Each side takes text of at most 1,200 characters. The size is 4x6 or 6x9.

Follow it

prompt
Where is the letter to Anna Berg now?

The client calls stack_list_letters or stack_get_letter. The states are submitting, sent, in_transit, delivered, returned, failed, cancelled and tracking_stopped. Tracking stops 60 days after sending: a letter neither delivered nor returned by then is tracking_stopped. Reads are free.

A letter cannot be cancelled once it is sent, and its price is shown after sending, not before.

When a send is refused

  • 409 POSTAL_ADDRESS_NOT_ACTIVE - the account has no active street address.
  • 422 POST_REFUSED, reason address_undeliverable - the recipient address cannot be delivered to.
  • 422 POST_REFUSED, reason provider_refused - the letter provider declined the piece.
  • 400 POST_REFUSED, reason pdf_unreadable or too_many_pages - fix the file and send again.
  • 503 POST_UNAVAILABLE - the letter provider cannot be reached. Nothing was charged.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as letter.send, with the amount held.

Reference

Every field is on Post. Every tool is in the tool reference. The return address is set up in Street address.

Letters and postcards | Docs