Integrations / HTTP recipes

Connect the moment. Make the arrival physical.

Matterleaf turns a reliable event from the systems you already use into a letter, card, or approved custom mailing. Start with the provider-neutral API, then map the source fields that matter.

Read the API guide Open interactive reference

source eventpaid / enrolled / sent

Matterleaf APIone durable order

statusaccepted → mailed

HTTP
+
care

Read this first

These pages document generic HTTP and middleware recipes. They do not claim native apps, platform OAuth, one-click installs, marketplace listings, or live platform testing. The API contract is the source of truth; platform-specific adapters are customer-configured until those surfaces are built and verified.

On this page

Overview

One order contract, many starting points.

Commerce, CRM, lifecycle, and automation systems are useful sources of context. Matterleaf remains the canonical home for the mailing request, recipient snapshot, production state, and fulfillment history.

Trigger

Receive a paid order, workflow enrollment, event, or deliberate operator action.

Map

Resolve a product, validate the postal address, and build the canonical order payload.

Reconcile

Store the order ID, handle pending or failed payment, and reflect status back when useful.

Commerce

Shopify

Turn a paid order or a Shopify Flow event into one carefully mapped Matterleaf order.

Docs-only recipe

Account / plan prerequisiteA Shopify store on a plan that includes Flow’s Send HTTP Request action — currently documented as Grow, Advanced, or Plus — plus an order-paid trigger/use case. Confirm Flow availability for the store.

TriggerOrder paid event or Shopify Flow → Send HTTP Request

Action / modulePOST /v1/orders (or /v1/batches for several orders)

AuthMatterleaf bearer key in a server-side secret store, plus the store credential with the minimum Admin API access needed to read the order.

Field mappingorder.id → external_reference and idempotency key; shipping address → recipient; line-item properties, order notes, or metafields → message and product fields; requested send date → scheduled_for.

Platform boundary

This recipe is not a Shopify app and does not include Shopify OAuth or an App Store listing. Flow’s HTTP action expects a fast response; use an intermediary when you need asset uploads, durable retries, or status polling.

Verification: Not smoke-tested against a live Shopify store from this checkout.

CRM

HubSpot

Let a workflow custom-code action or small integration service send a thoughtful note from a contact, company, or deal.

Docs-only recipe

Account / plan prerequisiteFor the current workflow webhook path, Data Hub Professional or Enterprise is required, plus Workflows and the relevant custom-code or HTTP-capable action. Availability and plan requirements must be confirmed for the target portal.

TriggerWorkflow enrollment, deal stage change, or a custom-code action

Action / modulePOST /v1/orders; poll the order or batch detail for status write-back

AuthMatterleaf bearer key in HubSpot secret storage or an external secret manager. Keep CRM permissions limited to the records and properties the workflow needs.

Field mappingPortal ID + contact ID → external_reference; custom code or a relay derives the deterministic Idempotency-Key; contact name and postal properties → recipient; deal/workflow message → message; returned order ID, status, schedule, tracking, and failure → custom HubSpot properties.

Platform boundary

This is not a HubSpot app, public OAuth connection, or Marketplace listing. Direct no-code delivery of the nested Matterleaf payload with a deterministic Idempotency-Key is unverified and not promised; the supported approach is a custom-code action or relay, especially when the workflow cannot safely retain the raw response or handle nested JSON.

Verification: No HubSpot portal execution has been verified from this checkout.

Lifecycle

Klaviyo

Use a flow event as the start of a physical touch, while keeping postal consent and order status explicit.

Docs-only recipe

Account / plan prerequisiteKlaviyo Flows, a user with 2FA for adding or editing the Flow webhook action, and an HTTPS endpoint that can receive POST requests.

TriggerKlaviyo Flow webhook action or an intermediary listening for flow events

Action / modulePOST /v1/orders; use a receiver or scheduled job for status updates

AuthMatterleaf bearer key and a Klaviyo private/API credential stored separately in server-side secrets. Do not put either secret in a profile, event, or template.

Field mappingProfile ID + event ID → external_reference and idempotency key; profile address → recipient; rendered flow message → message; event send date → scheduled_for; returned order ID → a controlled profile or event property for later reconciliation.

Platform boundary

This is not a native Klaviyo app or OAuth connection. Flow webhooks are POST-only and provider retries are controlled by Klaviyo; a separate receiver is needed for signed Matterleaf callbacks and raw-body verification. Email/SMS opt-in is not automatically postal consent.

Verification: No Klaviyo flow has been smoke-tested from this checkout.

Automation

Zapier

Connect almost any trigger app with a JSON-capable HTTP step and a replay-safe send key.

Generic HTTP recipe

Account / plan prerequisiteA Zapier account with Webhooks by Zapier and its Custom Request action, with plan and credential availability confirmed for the workspace.

TriggerWebhooks by Zapier → Custom Request

Action / modulePOST /v1/orders; optionally GET /v1/orders/{orderId} or /v1/batches/{batchId}

AuthKeep the Matterleaf key in a private auth field when available. If the Zap exposes credentials or raw webhook bytes, place a small server-side relay in front of it.

Field mappingSource event ID → Idempotency-Key and metadata.source_event_id; source record ID → external_reference; mapped recipient/message fields → configuration; send date → scheduled_for.

Platform boundary

This is not a published Zapier app with a native connection. Webhooks by Zapier availability and credential visibility depend on the account and plan. A Catch Hook should not be assumed to provide a raw-byte verification boundary.

Verification: No live Zap has been smoke-tested from this checkout.

Automation

Make

Compose a scenario from an HTTP module, a Data Store, and an optional custom webhook receiver.

Generic HTTP recipe

Account / plan prerequisiteA Make account with the HTTP app and its Make a request module; add a Data Store when the scenario needs durable deduplication or polling state.

TriggerSource trigger → HTTP / Make a request

Action / modulePOST /v1/orders or /v1/batches; route response status and error.code explicitly

AuthStore the Matterleaf key in a Make connection or encrypted variable. Keep it out of bundles, iterators, logs, and mapped fields.

Field mappingSource event ID → Idempotency-Key; source record ID → external_reference; recipient bundle → configuration.recipient; message/template output → configuration.message; scenario and source IDs → metadata.

Platform boundary

This is not a native Make app or published module. Use a Data Store for order IDs, batch IDs, cursors, and resource sequence numbers. Use an external receiver when the custom webhook cannot preserve raw bytes for HMAC verification.

Verification: No live Make scenario has been smoke-tested from this checkout.

Provider-neutral

Direct API / custom integrations

For an internal service, serverless function, data pipeline, or a platform not listed above, call Matterleaf directly from a trusted server.

API documented

TriggerYour system’s event, job, queue, or operator action

Action / moduleGET /v1/products → POST /v1/orders → GET /v1/orders/{orderId}

AuthCustomer-scoped Authorization: Bearer wl_… key, kept server-side

Field mappingitems[].configuration.recipient, message, product-specific fields, external_reference, and metadata

Canonical send shape

POST /v1/orders
Authorization: Bearer wl_live_…
Idempotency-Key: source:record:event:v1

{
  "items": [{
    "product_id": "handwritten",
    "configuration": {
      "recipient": { "name": "Ada Lovelace", "address": "1 Main St", "city": "Denver", "state": "CO", "zip": "80202" },
      "message": "A note from our team."
    }
  }]
}

Verification: The public guide documents the API behavior; it does not make a provider-specific staging or production test claim.

Shared reliability guidance

Make every send explainable.

All of the recipes use the same operational shape. Build the durable parts once, then keep each source adapter thin.

Prerequisites

A Matterleaf customer API key with only the scopes this workflow needs.
A product slug and configuration schema from GET /v1/products.
A complete postal address and a clear business rule for postal consent.
Server-side secret storage plus durable storage for source IDs and Matterleaf IDs.

Stable idempotency

Derive the key from the source account, source event or object, and intended action:

shopify:store:1001:paid:v1

Reuse the exact key and body after a timeout. A changed body with the same key is an idempotency_conflict, not an invitation to create a second order.

Success, pending, error

Persist the returned request ID and resource IDs. Treat HTTP status plus error.code as the routing signal, not a generic “failed” flag.

Outcome	What the integration should do
Accepted / scheduled	The API accepted and funded the order, or held it for a future release. Keep the returned order ID and poll for the production state.
Pending payment	The order is durable while funding is completed. Do not create another order for the same source event; recover the existing order if payment fails.
Batch accepted	A batch returns 202 and independently addressable child results. Persist the batch and item IDs; partial success and pending-payment children are expected. If interrupted, replay the exact same body with the original key; there is no autonomous batch recovery.
Error	Use error.code and request_id to decide whether to fix input, fund the account, retry transport, or ask for help. A same-key/different-body request is an idempotency conflict.

Transport retry rule: retry timeouts, connection failures, 429 responses, and temporary 5xx responses with bounded backoff. Do not blindly retry malformed input, missing permissions, invalid state, payment failure, cancellation errors, or idempotency conflicts. For payment recovery, keep the original order ID and use the documented payment-retry route. Wallet credits are used first; automatic recharge is never initiated unless auto_recharge_settings.enabled is true. A saved card or retry request alone is not consent to charge. When enabled, the saved top_up_amount_cents and monthly_limit_cents policy is used subject to per-charge and monthly guardrails, not a deficit override. A configured top-up that remains insufficient leaves the order recoverable without an unbounded loop. Cancellation restores the wallet allocation once; it is not a card refund.

Start a workflow

Bring the first real event.

Tell us which system is the source, what should trigger the send, and what you need to write back. We’ll help choose the right product schema and first test path.

Request API access Review the API guide hello@matterleaf.com