* Jessica in Oklahoma City just kept a postcard after clearing her Gmail promotions tab* Paul in Cincinnati, OH just booked another duct cleaning after receiving a postcard* Marta in Walla Walla, WA just pinned a lunch coupon to the fridge* Tyler in Tupelo, MS just scanned a roofer's postcard before the next storm rolled in* Anita in Scranton, PA just handed a chimney sweep card to her neighbor* Devon in Bozeman, MT just booked a tune-up from the card sitting by the keys* Renee in Marfa, TX just saved a salon postcard for Saturday* Owen in Traverse City, MI just booked the plumber whose card beat the inbox* Priya in Ames, IA just used a postcard offer after skipping three ad emails* Caleb in Beaufort, SC just booked patio cleaning from the card on his counter* Jessica in Oklahoma City just kept a postcard after clearing her Gmail promotions tab* Paul in Cincinnati, OH just booked another duct cleaning after receiving a postcard* Marta in Walla Walla, WA just pinned a lunch coupon to the fridge* Tyler in Tupelo, MS just scanned a roofer's postcard before the next storm rolled in* Anita in Scranton, PA just handed a chimney sweep card to her neighbor* Devon in Bozeman, MT just booked a tune-up from the card sitting by the keys* Renee in Marfa, TX just saved a salon postcard for Saturday* Owen in Traverse City, MI just booked the plumber whose card beat the inbox* Priya in Ames, IA just used a postcard offer after skipping three ad emails* Caleb in Beaufort, SC just booked patio cleaning from the card on his counter

Documentation

Everything between your list and the mailbox.

Connect an audience, design a 6x9 card, and move a drop to press. These guides cover every step, plus the MCP surface for teams who want to automate it.

/
Get Started TodayOpen the dashboard

Transport

MCP Streamable HTTP

Auth

Bearer tokens

Mail models

Campaign or one-off

Money model

Cards and credits

Overview

What Postcards.ai handles

Think of Postcards.ai as the direct-mail operating layer: audience selection, creative assets, billing, fulfillment, and mailing status in one place.

Neighborhood prospecting

Build local prospecting audiences from USPS carrier routes when the goal is reaching nearby households.

Integration audiences

Use imported customers or synced data from Square, MoeGo, and Jobber to target retention and win-back programs.

Two ways to mail

Run a drop for an audience or mail a single postcard to one recipient with PDF URLs and credits.

Operational controls

Billing, credits, mail history, and customer integrations are part of the same surface.

The important mental model is simple: decide who should receive mail, what the creative should say, and when the business should spend money. Postcards.ai turns that decision into a mailed postcard, with billing, fulfillment, and status tracking already built in.

Quick Start

The shortest path to a working mail workflow

A reliable flow starts with authentication, a lightweight state check, and then the smallest drop model that matches the task.

Step 01

Connect to the Postcards.ai MCP endpoint

For developer or agent workflows, use an MCP client that supports Streamable HTTP and connect it to https://mcp.postcards.ai/mcp. Operators can still run local-business campaigns directly from the dashboard.

Step 02

Get a bearer token

Either mint a personal access token from Settings or call the bootstrap tools to register or log in and receive a fresh token.

Step 03

Confirm sensitive writes

Read-only tools can run with the bearer token alone. Mutating or sensitive tools also need the server-issued confirmation_token from Macey's pending action preview.

Step 04

Pick the correct drop model

Use campaigns for saved audiences, built-in customer segments, and neighborhood mailings. Use one-off mailpieces for exactly one recipient with pre-rendered PDFs.

Step 05

Read before you write

A good workflow typically starts with whoami, billing, segment preview, customer state, or postcard specs before spending money or credits.

Bootstrap

Bootstrap a token from the MCP surface itself

Example
{
  "name": "postcards_ai_login_account",
  "arguments": {
    "email": "ops@coffee.example",
    "password": "••••••••",
    "accept_terms_and_privacy": true,
    "access_token_name": "GPT Agent"
  }
}

Prospecting + Audiences

Build audiences from neighborhoods or customer data

The current product supports both prospecting audiences and retention audiences. Keep the distinction clear because they come from different integrations and data sources.

Neighborhood prospecting

Search a ZIP code in the dashboard, choose USPS carrier routes, and save them as a carrier-route audience for local household prospecting.

Customer retention

Create saved audiences from Square, MoeGo, or Jobber when you need behavior-based filters, or use internal imports for mailing-address audiences.

Built-in MCP segments

The MCP campaign path supports lapsed, new_customers, vip, all_customers, and birthday segments through segment preview and campaign creation.

Saved audiences over MCP

Carrier-route lookup, geographic radius audiences, customer-integration imports, audience preview, saved-audience CRUD, and audience_id campaign launches are exposed through MCP.

Audience

Rails API carrier-route audience criteria for neighborhood prospecting

Example
{
  "method": "POST",
  "path": "/api/v1/audiences",
  "audience": {
    "name": "Neighborhood prospecting - 10014",
    "criteria": {
      "audience_type": "carrier_routes",
      "provider": "usps_eddm",
      "address_provider": "melissa",
      "search_zip": "10014",
      "carrier_routes": [
        {
          "zip": "10014",
          "route": "C001",
          "count": 412
        }
      ],
      "include_names": false
    }
  }
}

Audience

Rails API customer-source audience criteria for retention

Example
{
  "method": "POST",
  "path": "/api/v1/audiences",
  "audience": {
    "name": "Square lapsed 60-day customers",
    "criteria": {
      "customer_source": "square",
      "lapsed_days": 60,
      "zip": "10014"
    }
  }
}

Authentication

Use bearer tokens and keep them in workflow state

Postcards.ai uses personal access tokens for normal authenticated operations. A connected workflow can bootstrap a token or receive one from an operator.

Bootstrap tools

Use postcards_ai_register_account or postcards_ai_login_account when the connected workflow needs to self-serve account creation or login. Bootstrap tokens are narrow by default and do not manage other tokens.

Operator-managed tokens

An operator can create a personal access token in Settings inside this deployment and hand it to the workflow through its normal secret-management path.

Token management

Connected workflows can list, create, and revoke personal access tokens with the dedicated token tools only when they have an explicitly scoped token-management token.

Confirmation-gated writes

Mutating and sensitive MCP tools require a confirmation_token from a matching Macey pending action preview. The token is bound to the exact tool arguments and is consumed once.

HTTP

Connection settings your MCP client should use

Example
Marketing site: this deployment
Operator app: this deployment
MCP endpoint: https://mcp.postcards.ai/mcp

Authorization: Bearer <personal_access_token>
Accept: application/json, text/event-stream

Remember

The same token protects tools and resources.

If the workflow reads artifact resources or preview/PDF URLs, it should continue using the same bearer token. A good implementation stores the token once and reuses it across the full workflow.

postcards_ai_list_access_tokenspostcards_ai_create_access_tokenpostcards_ai_revoke_access_token

Mail Models

Decide between campaigns and one-off mailpieces

Most implementation mistakes come from choosing the wrong drop model. Postcards.ai exposes both because they solve different jobs.

Campaigns

Best when the job is audience-level: local prospecting, a saved audience, or a customer segment.

Use with saved audiences, built-in segments, design reuse, and campaign payment flow.
Good for neighborhood prospecting, win-back, VIP, birthday, new-customer, or all-customer programs.
Typical MCP path: preview or create audience → create/update design → create campaign → pay campaign.
USPS carrier-route and radius prospecting are available through MCP via route lookup, route preview, saved audiences, and audience_id campaigns.

One-off postcards

Best when exactly one postcard should go to exactly one recipient right now.

Use when you already have front and back PDF URLs.
Good for thank-you cards, follow-ups, concierge outreach, or support recovery.
Typical path: specs → preflight PDFs → call the single-postcard tool → review the send record.

One-Off Mailpieces

Use the single-postcard flow when the job is exactly one mailpiece

The one-off mail path is intentionally simple. The workflow provides front and back PDF URLs, recipient identity, and the mailing address.

Step 01

Fetch specs

postcards_ai_get_postcard_specs

Ask the platform for the current machine-readable PDF requirements before generating or validating creative.

Step 02

Run preflight

postcards_ai_preflight_single_postcard_pdfs

Validate that both PDFs are readable, one page each, and structurally acceptable before using credits.

Step 03

Mail the postcard

postcards_ai_send_single_postcard

Provide front/back PDF URLs, recipient identity, and the mailing address. This is the normal one-call mail path.

Step 04

Review send record

postcards_ai_get_single_postcard

Persist the returned mailpiece id so the workflow can inspect the send record or attach the mailed postcard to a customer record.

One-off

Minimal single-mailpiece payload

Example
{
  "name": "postcards_ai_send_single_postcard",
  "arguments": {
    "confirmation_token": "<server-issued confirmation token>",
    "front_pdf_url": "https://assets.example.com/postcards/vip-front.pdf",
    "back_pdf_url": "https://assets.example.com/postcards/vip-back.pdf",
    "recipient_name": "Jordan Lee",
    "to_address": {
      "address_line1": "123 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105"
    },
    "description": "VIP thank-you card",
    "metadata": {
      "trigger": "post-purchase",
      "customer_id": "cus_8421"
    }
  }
}

Important constraints

One-off mailpieces use prepaid credits, not a per-mailpiece card charge.

Preflight is structural. It checks file shape and readability, not every creative-quality concern.

Exactly one page per PDF is the safe assumption for the simple-upload path.

If the workflow needs a two-step path, use postcards_ai_prepare_single_postcard before later submission with postcards_ai_send_prepared_single_postcard. Both write steps still require a matching confirmation token.

Campaigns

Use campaigns for segments, programs, and repeatable workflows

Campaigns are the better fit when the job is list-level rather than one postcard to one person.

Step 01

Preview the audience

postcards_ai_preview_segment

For MCP-driven customer segments, start with recipient count and sample recipients so the workflow can decide whether the campaign is worth sending.

Step 02

Pick or build creative

postcards_ai_list_templates / postcards_ai_create_design / postcards_ai_update_design

Reuse an existing design, start from a template, or persist AI-generated creative as a design asset.

Step 03

Generate print-ready PDFs

postcards_ai_generate_design_pdf

Convert the stored design into artifact endpoints for previews and print-ready PDFs.

Step 04

Create the draft campaign

postcards_ai_create_campaign

Attach a design plus either built-in segment parameters or a saved audience_id to a named campaign draft.

Step 05

Fund the drop

postcards_ai_create_campaign_payment_intent / postcards_ai_pay_campaign / postcards_ai_pay_campaign_with_credits

Campaigns can be paid with a Stripe payment intent or prepaid credits, then submitted for fulfillment.

Step 06

Watch mail history

postcards_ai_list_postcard_mailings / postcards_ai_get_postcard_mailing

Use the unified mailings history to audit what was sent to print and why.

Campaign

Create a campaign draft from a segment and design

Example
{
  "name": "postcards_ai_create_campaign",
  "arguments": {
    "confirmation_token": "<server-issued confirmation token>",
    "name": "Lapsed 90-day win-back",
    "segment": "lapsed",
    "design_id": 42,
    "segment_params": {
      "days": 90
    }
  }
}

Working pattern

Use segment, saved-audience, radius-audience, or carrier-route preview first so the workflow understands audience size and shape.

Persist the design id and campaign id after creation. Most later steps only need those ids.

Generate PDFs before sending so the workflow can inspect artifact resources or previews.

Use the mailings tools as the campaign follow-up surface after payment and submission.

Design + Creative

Generate creative, then manage design state explicitly

The generation tools produce postcard concepts. The design tools persist selected work as reusable product state.

Creative flow

Ingest → generate → select → persist

Use postcards_ai_ingest_site when the workflow needs brand context from a live website.

Use postcards_ai_generate_variations to create editable AI postcard options.

Use feedback in the guided flow to generate a fresh round of options instead of patching an existing canvas. Logo and photo enhancement tools are available when brand assets need cleanup before layout.

Use the guided design tools when you want the same question-and-answer design flow exposed in the app.

When the result is good enough, persist it with postcards_ai_create_design or postcards_ai_update_design.

Creative

Generate a postcard concept from brand context

Example
{
  "name": "postcards_ai_generate_variations",
  "arguments": {
    "confirmation_token": "<server-issued confirmation token>",
    "purpose": "Win back lapsed cafe customers with a warm neighborhood offer",
    "website": "https://harborcoffee.example",
    "offer": "Free pastry with any drink this week",
    "style": "Editorial, tactile, neighborhood premium"
  }
}
The crucial design principle is that prompts are not the whole state. If the workflow needs to revisit or reuse a postcard later, it should persist the design object and its PDF artifacts rather than only saving the prompt that created it.

Resources

Use MCP resources for read-only context or artifact links

Resources are useful when a connected workflow wants stable context without triggering a write flow. Artifact resources are especially useful because they expose preview and PDF URLs for saved designs and campaigns.

URI
Returns
Why to use it
postcards_ai://account/me
Current user and business
Check the operating account before a workflow does anything expensive.
postcards_ai://designs/{id}
Design JSON plus artifact endpoints
Inspect a saved design and find its preview/PDF links.
postcards_ai://designs/{id}/artifacts
Front/back preview and PDF URLs
Pull creative artifacts without re-fetching the full design.
postcards_ai://campaigns/{id}
Campaign JSON plus artifact endpoints
Review a campaign as an object a connected workflow can reason about or summarize.
postcards_ai://campaigns/{id}/artifacts
Front/back preview and PDF URLs
Inspect campaign creative assets after PDF generation.
postcards_ai://postcard_mailings
Recent postcard mailing history
Use as the audit trail across campaigns and one-off mailpieces.
postcards_ai://postcard_mailings/{id}
Single mailing record plus related links
Fetch one mailing record and follow the related design or campaign.
postcards_ai://single_postcard_sends/{id}
One-off send plus PDF artifact endpoints
Inspect a prepared or submitted single postcard send.

Tool Map

The full MCP surface, grouped by job

These groups match the current MCP server tool list so connected workflows can choose the next tool without scanning the entire catalog every time.

Bootstrap + account

postcards_ai_register_accountpostcards_ai_login_accountpostcards_ai_get_user_invitationpostcards_ai_accept_user_invitationpostcards_ai_whoamipostcards_ai_update_account

Admin + team

postcards_ai_list_businessespostcards_ai_update_businesspostcards_ai_get_platform_settingspostcards_ai_update_platform_settingspostcards_ai_get_teampostcards_ai_invite_team_memberpostcards_ai_update_team_userpostcards_ai_remove_team_userpostcards_ai_revoke_team_invitation

Assistant + handoff

postcards_ai_list_assistant_sessionspostcards_ai_create_assistant_sessionpostcards_ai_get_assistant_sessionpostcards_ai_get_assistant_human_repliespostcards_ai_chat_with_assistantpostcards_ai_sync_assistant_conversationpostcards_ai_request_assistant_conversation_handoffpostcards_ai_get_assistant_conversation_human_replies

Tokens + billing

postcards_ai_list_access_tokenspostcards_ai_create_access_tokenpostcards_ai_revoke_access_tokenpostcards_ai_get_billingpostcards_ai_create_setup_intentpostcards_ai_confirm_setuppostcards_ai_set_default_payment_methodpostcards_ai_remove_payment_methodpostcards_ai_create_credit_payment_intentpostcards_ai_confirm_credit_purchasepostcards_ai_purchase_credits_with_saved_card

Audiences + carrier routes

postcards_ai_preview_segmentpostcards_ai_list_customerspostcards_ai_get_customerpostcards_ai_get_customer_sourcespostcards_ai_import_customerspostcards_ai_list_audiencespostcards_ai_get_audiencepostcards_ai_preview_audiencepostcards_ai_create_audiencepostcards_ai_update_audiencepostcards_ai_delete_audiencepostcards_ai_list_carrier_routespostcards_ai_nearby_carrier_routes_by_zippostcards_ai_nearby_carrier_routes_by_addresspostcards_ai_preview_carrier_routespostcards_ai_list_merge_fieldspostcards_ai_list_templatespostcards_ai_get_templatepostcards_ai_get_postcard_specs

Design + creative

postcards_ai_list_designspostcards_ai_get_designpostcards_ai_create_designpostcards_ai_update_designpostcards_ai_delete_designpostcards_ai_generate_design_pdfpostcards_ai_list_design_parse_runspostcards_ai_get_design_parse_runpostcards_ai_create_design_parse_runpostcards_ai_batch_design_parse_runspostcards_ai_promote_design_parse_runpostcards_ai_get_design_parse_run_artifact_endpointpostcards_ai_get_ai_template_librarypostcards_ai_ingest_sitepostcards_ai_generatepostcards_ai_generate_editable_aipostcards_ai_generate_variationspostcards_ai_generation_statuspostcards_ai_regenerate_imagepostcards_ai_enhance_logopostcards_ai_enhance_photopostcards_ai_start_guided_designpostcards_ai_continue_guided_designpostcards_ai_check_guided_designpostcards_ai_select_guided_design_optionpostcards_ai_save_guided_design

Campaigns + mail history

postcards_ai_list_campaignspostcards_ai_get_campaignpostcards_ai_create_campaignpostcards_ai_update_campaignpostcards_ai_delete_campaignpostcards_ai_run_campaign_merge_field_preflightpostcards_ai_run_campaign_fulfillment_preflightpostcards_ai_create_campaign_payment_intentpostcards_ai_pay_campaignpostcards_ai_pay_campaign_with_creditspostcards_ai_get_campaign_attribution_summarypostcards_ai_list_fulfillment_ops_campaignspostcards_ai_get_fulfillment_ops_campaignpostcards_ai_reconcile_fulfillment_ops_campaignpostcards_ai_list_postcard_mailingspostcards_ai_get_postcard_mailing

One-off mailpieces

postcards_ai_list_single_postcardspostcards_ai_prepare_single_postcardpostcards_ai_preflight_single_postcard_pdfspostcards_ai_send_single_postcardpostcards_ai_get_single_postcardpostcards_ai_send_prepared_single_postcardpostcards_ai_get_single_postcard_artifact_endpoints

Integrations

postcards_ai_square_statuspostcards_ai_square_auth_urlpostcards_ai_square_callbackpostcards_ai_square_syncpostcards_ai_square_disconnectpostcards_ai_moego_statuspostcards_ai_moego_connectpostcards_ai_moego_syncpostcards_ai_moego_disconnectpostcards_ai_jobber_statuspostcards_ai_jobber_auth_urlpostcards_ai_jobber_completed_jobspostcards_ai_jobber_callbackpostcards_ai_jobber_syncpostcards_ai_jobber_disconnect

Operating Model

How good workflows behave around direct mail

The fastest path is not always the best path. A good Postcards.ai workflow behaves like an operator with judgment, not like a blind function caller.

Good habits

Use read tools first. A disciplined workflow checks account, billing, and audience state before creating a chargeable action.
Ask Macey for a pending action preview before mutating or sensitive MCP tools, then pass the exact confirmation_token with the tool arguments.
Choose the smallest valid drop model. If one recipient and finished PDFs are enough, use the one-off path instead of inventing a campaign.
Persist ids aggressively. Keep design ids, campaign ids, postcard ids, and mailings ids in your workflow state so follow-up calls are cheap.
Treat direct mail as a physical artifact. Validate page specs, tone, offer, and address quality before calling a mail tool.
Use mail history as the source of truth. When reconciling state, ask the mailings tools or resources instead of guessing.

When something fails

Authentication failed: refresh the bearer token, then retry whoami before attempting any mutations.
A mutating MCP call is missing confirmation: ask Macey for a fresh pending action preview and retry with its confirmation_token.
Not enough credits for a one-off mailpiece: call billing, top up credits, then re-run the mail action.
Campaign payment blocked: create a payment intent first, then pay the campaign with the resulting payment_intent_id.
PDF preflight failed: regenerate or replace the front/back PDFs rather than forcing the design through.
The workflow is unsure which creative asset is current: read the design or campaign artifact resources instead of relying on stale local memory.

Ready to connect a workflow

Give your workflow a real mail channel.

Use the docs as the operating model: authenticate once, choose the right mail path, persist ids, and let Postcards.ai handle the physical-mail mechanics.

Get Started TodaySign in