Your first mailing.

One complete recipe. No card, provider account, or installation required beyond curl and jq.

Start in test mode: generate a real PDF proof, then simulate a send without charges or postal delivery. Example addresses below are test fixtures.

Start with Bash, curl, and jq

# Requires curl and jq. This is sandbox-only; no card is needed.
set -eu
BASE='https://postalmuse.com'
KEY="$(date +%s)-$RANDOM"
SESSION=$(curl --fail-with-body -sS "$BASE/v1/sessions" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: session-$KEY" \
  -d '{"mode":"sandbox"}')
TOKEN=$(printf '%s' "$SESSION" | jq -r .token)
DRAFT=$(curl --fail-with-body -sS "$BASE/v1/drafts" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: draft-$KEY" \
  -d '{"kind":"postcard","purpose":"operational","to":{"name":"Sandbox Recipient","address_line1":"100 Example Lane","address_city":"San Francisco","address_state":"CA","address_zip":"94107","address_country":"US"},"from":{"name":"Sandbox Sender","address_line1":"200 Sample Street","address_city":"San Francisco","address_state":"CA","address_zip":"94107","address_country":"US"},"content":{"type":"template","template_id":"everyday_note","template_version":"1","variables":{"title":"Thanks for everything.","message":"A little note to say thank you. It means a lot."}}}')
ID=$(printf '%s' "$DRAFT" | jq -r .id)
for attempt in $(seq 1 30); do
  DRAFT=$(curl --fail-with-body -sS "$BASE/v1/drafts/$ID" -H "Authorization: Bearer $TOKEN")
  STATUS=$(printf '%s' "$DRAFT" | jq -r .status)
  [ "$STATUS" = ready ] && break
  [ "$STATUS" = needs_changes ] && { printf '%s\n' "$DRAFT"; exit 1; }
  sleep 1
done
[ "$STATUS" = ready ] || { echo 'Still preparing. Poll this same draft later.'; exit 1; }
# Open this PDF and inspect it before committing:
printf '%s' "$DRAFT" | jq -r .proof.pdf_url
COMMIT=$(printf '%s' "$DRAFT" | jq '{draft_revision:.revision,quote_id:.quote.id,manifest_hash:.manifest_hash,max_total_cents:.quote.total_cents,currency:"USD"}')
# Sandbox simulation only. For live purchases, use /checkout instead.
curl --fail-with-body -sS "$BASE/v1/drafts/$ID/send" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: send-$KEY" -d "$COMMIT"
# Save the returned mailing ID; GET /v1/mailings/{id} for status.
# Retry an operation with the SAME key and payload. Don't create a replacement.

Ready for real mail?

Live sending is currently unavailable. Check capabilities before creating a live session.