moltmailer
Log inSend a card

How it works (bots)

Agentic bots can generate templates, draft postcards for free, then confirm exactly once — with guardrails and zero duplicate sends.

Safety Valve contract
  • /draft is free (safe, no spend, no mail)
  • /confirm is the only spend attempt (may return pending_approval)
  • Idempotency blocks duplicates

Get an API key

Create one in /dashboard/settings. You’ll only see the full key once.

Endpoints

  • POST /api/v1/photos/import → import a reference photo (optional)
  • POST /api/v1/prompts/generate → generate a recommended prompt (optional)
  • POST /api/v1/templates/generate → template from prompt (optional)
  • POST /api/v1/postcards/draft → create draft (free)
  • POST /api/v1/postcards/:id/confirm → spend attempt / approval gate
  • GET /api/v1/postcards/:id → status + receipt token

Curl: generate → draft → confirm

# 1) (optional) generate a template
curl -X POST https://www.moltmailer.com/api/v1/photos/import \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://example.com/jenny.jpg","label":"jenny"}'

# 1b) (optional) generate a recommended prompt
curl -X POST https://www.moltmailer.com/api/v1/prompts/generate \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"occasion":"Birthday","vibe":"Funny + warm","recipient_name":"Jenny","include_text":"short","user_idea":"A crab holding a cake, retro postcard style","has_starting_photo":true}'

# 2) (optional) generate a template (supports up to 8 reference photos)
curl -X POST https://www.moltmailer.com/api/v1/templates/generate \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A funny crab holding a birthday cake, retro postcard style","user_photo_ids":["PHOTO_UUID_1","PHOTO_UUID_2"]}'

# 3) draft (free)
curl -X POST https://www.moltmailer.com/api/v1/postcards/draft \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"recipient_name":"Jenny Rosen","recipient_address":{"country_code":"US","line1":"1 Main St","line2":null,"city":"New York","region":"NY","postal_code":"10001"},"message_text":"Happy birthday!","template_id":"TEMPLATE_UUID"}'

# 4) confirm (spend attempt; may return pending_approval)
curl -X POST https://www.moltmailer.com/api/v1/postcards/DRAFT_UUID/confirm \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"agent-run-001"}'

Approval flow

If confirm returns pending_approval, a human approves it in /dashboard/approvals. No spend happens until then.

Photos vs Templates
  • Photos are raw reference images (any size). They’re inputs for generation/editing.
  • Templates are complete postcard fronts (print-ready). Drafts require a template_id.

Recommended bot flow

  1. (Optional) Import 1–8 reference photos → collect photo IDs
  2. (Optional) Generate a recommended prompt (Gemini text)
  3. Generate a template (Gemini image) with prompt + optional user_photo_ids
  4. Create a draft (free)
  5. Confirm (the only spend attempt) with idempotency_key
  6. If pending approval: wait for human approve, then poll status