Workflow Documentation

How local businesses mail postcards with Postcards.ai.

Postcards.ai gives operators and connected workflows a direct-mail surface for prospecting nearby households, bringing back lapsed customers, and mailing one-off follow-ups. Use the dashboard for day-to-day local drops, or connect through MCP when another system needs to inspect state and move mail.

Start a dropOpen the dashboard

Transport

MCP Streamable HTTP

Connect an MCP client to /mcp when a tool or agent needs direct-mail access.

Auth

Bearer tokens

Operators manage account access in this deployment, or agents can bootstrap with the register/login tools.

Mail models

Campaign or one-off

Choose campaigns for neighborhood or customer audiences, and one-off mailpieces for a single recipient.

Money model

Cards and credits

Campaigns use the payment flow. One-off mailpieces use prepaid 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 /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

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 04

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 internal imports, Square, MoeGo, or Jobber, then filter by address, spend, order count, recency, or pet birthday month.

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.

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 when that is appropriate.

HTTP

Connection settings your MCP client should use

Example
Marketing site: this deployment
Operator app: this deployment
MCP endpoint: /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 → check status.

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

Track delivery

postcards_ai_get_single_postcard

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

One-off

Minimal single-mailpiece payload

Example
{
  "name": "postcards_ai_send_single_postcard",
  "arguments": {
    "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.

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 mailed and why.

Campaign

Create a campaign draft from a segment and design

Example
{
  "name": "postcards_ai_create_campaign",
  "arguments": {
    "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 help produce postcard concepts and refinements. The design tools persist that work as reusable product state.

Creative flow

Ingest → generate → refine → 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 postcards_ai_refine and postcards_ai_regenerate_image to iterate instead of starting over. Logo and photo enhancement tools are available when the 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": {
    "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 mailed postcards
Use as the audit trail across campaigns and one-off mailpieces.
postcards_ai://postcard_mailings/{id}
Single mailed postcard plus related links
Fetch one mailed postcard 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_refinepostcards_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.
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.
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.

Start freeSign in