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": "a6", "cardOrientation": "portrait",
    "envelopeSizeSlug": "env-dl", "ink": "blue",
    "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
}
→ 201 { "order": { "id": "…", "status": "queued", "recipient": {…}, "card": {…}, "pricing": {…} } }

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": "express" }
] }
→ 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.
• 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 and follow the order.
• 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.