API & integrations

Every request carries an API key. Make one yourself under Dashboard → Developers: keys are shown once, and come in live and test modes.

Authorization: Bearer mmc_live_…

GET https://mailmycard.com/api/v1/me
→ { "object": "account", "accountId": "…", "key": { "id": "…", "mode": "live" } }

Errors come back as { "error": { "type", "message" } } with the usual codes: 400 invalid_request_error, 401 authentication_error, 402 insufficient_funds, 404 not_found, 409 idempotency_conflict.

A template is a card without a recipient: paper, ink, hand, the words or a designed layout, envelope and service. Make one in the dashboard (review step → “Save this card as a template”) or through the API.

POST /api/v1/templates
{
  "name": "Client thank-you",
  "design": {
    "cardSizeSlug": "postcard-4x6", "cardOrientation": "portrait",
    "envelopeSizeSlug": "env-625x425", "ink": "black",
    "font": { "slug": "caveat", "source": "preset" },
    "message": "Thank you for choosing us.", "signoff": "The team",
    "mailClass": "tracked"
  }
}
→ 201 { "template": { "id": "…", "name": "Client thank-you", "summary": "A6 card · portrait · Blue ink · Casual", … } }

GET /api/v1/templates · GET/PATCH/DELETE /api/v1/templates/{id}

A recipient is the only thing a template does not carry. Send an Idempotency-Key (any UUID) so a retry returns the same order rather than a second card.

POST /api/v1/templates/{id}/orders
Idempotency-Key: 6c8a…
{
  "recipient": { "name": "Priya Nair", "line1": "12 Marine Drive", "city": "Kochi",
                 "region": "KL", "postal": "682001", "country": "IN" },
  "quantity": 1,           // optional; "mailClass" and "returnAddress" override the template's
  "details": { "your_name": "Diljit", "date": "2019-03-12", "place": "Kochi, India" }
}
→ 201 { "order": { "id": "…", "status": "queued", "recipient": {…}, "card": {…}, "pricing": {…} } }

details make the card this person’s. Each fills the [placeholder] of the same name (your_name fills [Your name]; [Name] is the recipient’s first name unless you send one), and a card from a personal design is drawn from them: their star sign from month and day, the night sky over place on date. A template lists what it takes in its details. A card that would still show a placeholder is refused with missing_details, naming what to send, rather than written with brackets on it.

Up to 100 recipients per call, each placed on its own: one bad address never stops the others, and the reply says per item whether it was created, reused or refused. A ref of your own comes back with each result.

POST /api/v1/templates/{id}/orders/batch
Idempotency-Key: 9b1e…
{ "orders": [
    { "ref": "crm-1042", "recipient": { "name": "…", "line1": "…", "city": "…", "postal": "…", "country": "US" } },
    { "ref": "crm-1043", "recipient": { … }, "mailClass": "tracked" }
] }
→ 200 { "object": "batch", "created": 2, "reused": 0, "refused": 0,
        "results": [ { "index": 0, "ref": "crm-1042", "status": "created", "order": {…} }, … ] }

GET /api/v1/orders?limit=25&offset=0   → { "orders": [ … ], "hasMore": true, "nextOffset": 25 }
GET /api/v1/orders/{id}                → { "order": { "id", "status", "statusLabel", "recipient", "card",
                                            "quantity", "mailClass", "pricing", "createdAt", "updatedAt", … } }

Statuses: queued → writing → ready → mailed → delivered, with failed and cancelled when something goes wrong.

Register an https endpoint and choose events; each delivery is signed with the endpoint’s secret (whsec_…) so you can verify it came from us. Events: order.created and one per status (order.writing, order.mailed, …).

POST /api/v1/webhook-endpoints
{ "url": "https://example.com/hooks/mailmycard", "events": ["order.created", "order.mailed"] }
→ 201 { "id": "…", "secret": "whsec_…", "events": [...] }

GET /api/v1/webhook-endpoints · DELETE /api/v1/webhook-endpoints/{id}

Built on exactly these calls, and needing no code from you:

• Zapier — “MailMyCard: Send a Card” in any Zap, and triggers when a card is ordered, written, mailed or delivered. Connect with an API key.
• Shopify — a card for every paid order, sent to its shipping address. Dashboard → Integrations → Connect Shopify: one click on your store, nothing to paste.
• HubSpot — Dashboard → Integrations → Connect HubSpot, and “MailMyCard: Send a card” appears in every workflow’s action list. See the HubSpot setup guide.
• Pipedrive, Zoho CRM, Attio, monday.com, Keap, Close — Dashboard → Integrations → Connect your CRM: one click, and a card goes to the contact whenever a deal is won (in Keap, whenever the tag “MailMyCard: send a card” is applied). The webhook is registered for you.
• WooCommerce — Dashboard → Integrations → Connect WooCommerce: approve MailMyCard on your store and every paid order gets a card. No plugin, no keys to copy.
• Stripe — Dashboard → Integrations → Add an integration → Stripe: paste the endpoint’s signing secret, and every successful payment with a shipping address gets a card.
• Make and n8n — a Make app (Send a Card, Get an Order, Watch Cards) and then8n-nodes-mailmycard package, both over the API key.
• AI assistants (MCP) — point Claude, ChatGPT, Cursor or any MCP client at /api/mcp with your API key as the bearer token, and it can list your cards, send one, follow the order, and make and share digital cards.
• Google Sheets — share a sheet with “Anyone with the link”, paste the link under Dashboard → Integrations → Watch a Google Sheet, and every row added to it gets a card. No Google sign-in.
• HubSpot, Salesforce, Make, n8n, forms — a webhook URL with a secret that any workflow can POST a recipient to. Dashboard → Integrations → Generic webhook.
• A spreadsheet — Your cards → a template → “Send to a list”: upload a CSV from any CRM or shop and send the whole list.

Keys are made under Dashboard → Developers. For an integration that is not here, write to us.

A card sent as a link instead of by post: an envelope that opens on the recipient’s phone. Make one as a draft that only you can see, then unlock it to put the link live. The unlock is a one-time fee from your wallet, fixed in rupees (the price in each answer says how much) and safe to repeat: a card already paid for is not charged again. A test key cannot unlock.

POST /api/v1/digital-cards
{ "title": "Happy birthday, Amma", "message": "Many happy returns", "from_name": "Asha",
  "occasion": "birthday", "theme": "bloom", "flower": "roses", "light": "day" }
→ 201 { "object": "digital_card", "id": "7EFR5SJWJZ", "status": "draft", "url": "https://mailmycard.com/m/7EFR5SJWJZ",
        "price": { "inr": 99, "usd_cents": 103, "paid": false }, … }

PATCH /api/v1/digital-cards/{id}            change the words, occasion or look, before or after it is live
POST  /api/v1/digital-cards/{id}/unlock     → 200 { …, "status": "live", "charged": true }
                                              402 payment_required when the wallet is short
GET   /api/v1/digital-cards?limit=25        · GET /api/v1/digital-cards/{id}

occasion is birthday, celebration or quiet; theme is bloom (flowers on a table, the default), balloons, diwali, snow, autumn, ocean, hearts or classic; flower (for bloom only) is roses, peonies, sunflowers, lavender or cherry; light is day or night. Photos and video are added by the owner from the card’s edit_url. The MCP tools are create_digital_card, update_digital_card, unlock_digital_card, get_digital_card and list_digital_cards.

A card can carry a gift you already have, wrapped for the recipient to unwrap: send gift on create or update, or null to remove it. It needs a name and a code or an https url. We do not sell, issue or check the gift, and anyone with the card’s link can read the code, so set a pin if it should be private. You are emailed the first time it is unwrapped.

PATCH /api/v1/digital-cards/{id}
{ "gift": { "name": "Dinner for two", "code": "ABCD-1234", "url": "https://www.example.com/redeem",
            "note": "You pick the night." } }