# 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](/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

```text
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

```text
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

```text
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](/docs/api/account-post). Every tool is in the [tool reference](/docs/mcp-tools). The return address is set up in [Street address](/docs/account/address).
