Klaviyo + PostPilot Direct Mail Setup

How it works

Klaviyo holds your Shopify customer data, including mailing addresses. A Klaviyo Flow with a webhook action automatically pushes customers into PostPilot's API. PostPilot receives the contacts, verifies their addresses, and your automated campaign mails them a postcard — fully hands-off.

End-to-end flow (once live, this runs automatically):

Klaviyo Flow Triggers → Webhook Fires to PostPilot API → Address Verified → Contact Enters Segment → Postcard Mailed

What you'll need

A PostPilot account
A Klaviyo account connected to your Shopify store
A Klaviyo segment or flow you want to use as the trigger

Step-by-step guide

Step 1: Create an API connection in PostPilot

Log in to PostPilot and navigate to Integrations → API Connections.
Click New API Connection and give it a descriptive name (e.g., "Klaviyo").
Once created, click the clipboard icon to copy the full endpoint URL from the connection detail page — this contains your unique API key.
Keep this URL secure. Klaviyo will use it to send customer data to PostPilot.

Step 2: Set up a webhook in Klaviyo

In Klaviyo, go to Flows → Create Flow → Build your own.
Choose a trigger:
- Existing segment: Select "Segment" as the trigger to push everyone currently in it, plus anyone who enters in the future.
- Event-based: Select the appropriate trigger (e.g., "Placed Order", "Fulfilled Order") and add filters to match your targeting criteria.
Add a Webhook action in the flow builder.
Set Method to POST.
Add one header: Key: Content-Type, Value: application/json.
Paste your unique URL that you copied in Step 1 (URL below is only an example) and the exact JSON body below, then set the flow to Live.

Webhook URL

https://api.postpilot.com/v1/{YOUR_CONNECTION_KEY}/api_full_contact

Request body — JSON

{
  "reference_id": "",
  "email": "",
  "firstname": "",
  "lastname": "",
  "line1": "",
  "line2": "",
  "city": "",
  "state": "",
  "postal_code": "",
  "country": "",
  "custom_1": "your_unique_title_here",
  "custom_2": "",
  "custom_3": ""
}

Note: Address fields (Address1, City, Region, Zip, Country) are only available when the Shopify integration is active and the customer has placed at least one order. Profiles added through email signup only may not have address data — verify your Klaviyo profiles before launching.

Field reference

Field	What it does
`reference_id`	The customer's Klaviyo profile ID. Prevents duplicates — if the same customer triggers the flow again, their record is updated rather than duplicated.
`firstname` / `lastname`	Pulled automatically from the Klaviyo profile (synced from Shopify).
`line1` → `country`	The customer's mailing address. Klaviyo syncs the customer's default Shopify address.
`custom_1`	A unique title to identify this specific flow. Choose something descriptive (e.g., `vip_winback`, `high_spenders`, `post_purchase_30d`). This exact value is what you'll use in Step 3 to create a matching segment, so it must be consistent. Do not use spaces — only underscores. Each flow should have a different `custom_1` value.
`custom_2`	Optional additional data to print on the postcard (e.g., loyalty points, discount amount).
`custom_3`	Optional additional personalization (e.g., VIP tier, product name).

Step 3: Create a segment in PostPilot

From the API connection page, click Create Segment.
Add a filter: Custom 1 equals the unique title you entered in the custom_1 field in Step 2 — it must match exactly.
Save. This segment will include all contacts pushed from Klaviyo with that title.

Tip: If you have multiple Klaviyo flows sending to PostPilot, create a separate segment for each one by matching the unique custom_1 title from each flow.

Step 4: Test the integration

In Klaviyo, manually add a test profile to the segment that triggers the flow (or use Klaviyo's flow preview).
Verify the webhook fires successfully — Klaviyo shows webhook status in the flow analytics.
Wait for the contacts to process in PostPilot. Contacts go through address verification before appearing in the segment, so this is not instant (can take 3–5 hours).
Refresh the segment count in PostPilot to confirm the flow contacts appear.

Step 5: Create an automated campaign in PostPilot

In PostPilot, go to Campaigns → Create Campaign.
Select Automated as the campaign type.
Choose the segment you created in Step 3 as the audience.
Design your postcard and use merge tags to personalize:
- — Customer's first name
- — Any additional value you passed (if used)
- — Any additional value you passed (if used)
Set the campaign Live. PostPilot will automatically mail new recipients as they enter the segment from Klaviyo.

Best practices

Tip	Details
Address data	Klaviyo syncs the customer's default address from Shopify. If a customer has multiple addresses, only the default one is available.
Avoid duplicates	Always use for `reference_id`. Repeat triggers update the existing record rather than creating a new one.
One flow per campaign type	Create separate Klaviyo flows, PostPilot segments, and automated campaigns for each use case using different `custom_1` values.
Timing expectations	Contacts are not available instantly after the webhook fires. They go through an address verification pipeline before appearing in the segment. This can take 3–5 hours.
No rate limit concerns	Typical Klaviyo segment volumes are well within PostPilot's API limits. No throttling needed.
Segment naming	Use clear, consistent `custom_1` values so your PostPilot segments stay organized as you scale to multiple flows.

Alternative option: No mailing address? Use email match.

If your Klaviyo profiles don't have mailing addresses (e.g., email-only subscribers), use the email contact endpoint instead. PostPilot's MailMatch will find the customer's physical address from their email. Available for US addresses only.

Webhook URL — email endpoint

https://api.postpilot.com/v1/{YOUR_CONNECTION_KEY}/api_email_contact