Skip to content
English
Sign in
Go to the PostPilot app
  • There are no suggestions because the search field is empty.

API-Triggered Segments & MailMatch via API

PostPilot now supports sending direct mail via an API call from any external platform — like Klaviyo or your own system — using API-triggered segments instead of flows. You can also reach recipients you only have an email address for using our new MailMatch™ via API feature.

📌 Flows are being deprecated. All new API-driven campaigns should be built as segments going forward. This article covers the new approach.

💡 A note about Klaviyo: PostPilot has a native Klaviyo integration, and for most use cases that's the simplest way to get started. However, the API approach described in this article is useful even for Klaviyo users in cases where you need custom fields, advanced segmentation, or other capabilities not available through the native integration. We use Klaviyo JSON examples throughout this article as a consistent reference point — but the steps apply to any platform that can make an API call.

Overview

PostPilot's API connection now provides three distinct endpoints, each designed for a specific use case:

API Name Endpoint Best for Requires address?
MailMatch™ via API api_email_contact MailMatch™ campaigns — send via email only, PostPilot looks up the address No
API Full Contact api_full_contact Sending to contacts where you have a full mailing address Yes
Shopify Customer Events via API shopify_customer_event Triggering sends to existing Shopify customers based on events No (uses Shopify data)

In each case, the process is the same: your external system makes an API call to one of these endpoints, PostPilot updates the contact record, and a campaign targeting a matching segment picks it up and mails a postcard.

 

Setting Up Your API Connection

Before using any API endpoint, you'll need an active API connection in PostPilot.

  1. Go to Integrations → API Connection
  2. Click Manage under the API Connection card
  3. Click New Connection if one doesn't already exist, or select an existing connection to manage it

Inside the connection details page, you'll find the full endpoint URLs and example JSON bodies for all three endpoints. Each section includes a copy button to grab the exact URL for use in your external system.

⚠️ If you regenerate your API URLs (e.g., for security reasons), all three endpoints will change. You'll need to update them manually in any external systems.

 

MailMatch™ via API

MailMatch allows you to send postcards to contacts using only their email address — no mailing address required. PostPilot matches the email to a physical address on your behalf.

Step 1: Configure the API call in your external platform

In your external tool (e.g., Klaviyo), copy the endpoint URL for Create/Update API Email Contact from the API Connection details page, then configure a webhook block to POST to that URL:

POST api.postpilot.com/v1/{connection_id}/api_email_contact

Example JSON body for Klaviyo:

{
  "email": "",
  "fullname": " "
}

Note: The example above uses Klaviyo-specific template variables. If you're using a different platform, you'll need to adjust the field references to match how your system defines them. For example, your email field might be email.address instead of .

Step 2: Create the segment and campaign in PostPilot

  1. Go to Segments → New Segment
  2. Select the API Contacts with Email target
  3. Add a Contact updated date (relative) filter set to on or after 2 days ago to ensure only recently triggered contacts are included
  4. Create and launch a one-off or automated MailMatch campaign targeting this segment

✅ Every time a contact hits the webhook block in Klaviyo, PostPilot updates the contact record, it enters the segment, and the campaign mails a postcard — all automatically.

 

API Full Contact

Use this endpoint when you have the recipient's complete mailing address. This replaces the old API-triggered flow for full contact sends.

Step 1: Configure the API call in your external platform

Copy the Create/Update API Full Contact record URL from your API Connection details page, and configure a webhook block in Klaviyo (or any platform) to POST to it:

POST api.postpilot.com/v1/{connection_id}/api_full_contact

Example JSON body for Klaviyo:

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

Note: The example above uses Klaviyo-specific template variables. If you're using a different platform, you'll need to adjust the field references to match how your system defines them.

Step 2: Create the segment and campaign in PostPilot

  1. Go to Segments → New Segment
  2. Select API Contacts with Address
  3. Optionally add a Contact updated date (relative) filter to target only recently triggered contacts
  4. Create a one-off or automated campaign targeting this segment

 

Shopify Customer Events via API

This endpoint lets you trigger a postcard send to an existing Shopify customer based on an event — without needing to pass a full address.

Step 1: Configure the API call in your external platform

Copy the Shopify Customer Event URL from your API Connection details page:

POST api.postpilot.com/v1/{connection_id}/shopify_customer_event

The JSON body only requires an email or customer ID:

{
  "email": ""
}

Note: You can use email or customer_id — only one is required. The example above uses a Klaviyo-specific template variable. Adjust as needed for your platform.

Step 2: Create the segment and campaign in PostPilot

  1. Go to Segments → New Segment and create a Shopify customer segment
  2. Add an API Shopify customer event occurred (relative) filter
  3. Set the time window (e.g., on or after 2 days ago)
  4. Create a one-off or automated campaign targeting this segment

 

Using Custom Fields

All three API endpoints support up to three custom fields (custom_1, custom_2, custom_3). These serve two purposes:

 

Personalizing postcard content

Pass any dynamic value — like a pet name, product name, or offer code — through a custom field, then reference it as a dynamic variable in your postcard design.

{
  "email": "",
  "fullname": " ",
  "custom_1": ""
}

 

Driving advanced segmentation

Custom fields can also be used as filters in your segment, allowing you to route contacts to different campaigns based on the event type. For example, you can pass "custom_1": "email_unsubscribed" in the API call body, then filter your segment to only include contacts where Custom Field 1 is "email_unsubscribed".

💡 This is especially useful when replacing multiple flows that previously sent different postcards based on different triggers. Instead of multiple flow URLs, use one endpoint and differentiate with custom fields.

 

Migrating from Flows to API Segments

The new API segments are designed to be backwards-compatible with existing flow trigger URLs. This means you do not need to change webhook URLs or JSON bodies in your external system when migrating most simple setups.

Simple migration (one flow → one segment)

  1. Create an equivalent segment targeting API Full Contacts (or Shopify customers), filtered by recently updated contacts
  2. Create a one-off or automated campaign targeting that segment with the same postcard design
  3. Turn off the old flow
  4. Launch the campaign

Complex migration (multiple flows sending different designs)

If you previously used multiple flow trigger URLs to send different postcards based on different events, you'll need to update your setup to use custom fields for differentiation:

  1. Update each API call in your external system to use the single api_full_contact endpoint, adding a custom_1 value that identifies the event (e.g., "purchased" or "no_purchase")
  2. Create a separate segment in PostPilot for each event type, filtering by the corresponding custom field value
  3. Set up a dedicated campaign for each segment

 

When to Keep Using Flows

While API-triggered segments are the recommended approach for all new campaigns, the following integrations should continue using the existing flows setup:

Integration Reason
Recharge Recharge does not support customizing the JSON body in its webhook. Our native flows integration handles the required formatting automatically.
Omnisend Omnisend's webhook does not support custom JSON bodies. Use the existing native integration in flows.
Loyalty Lion Same as above — our native flows integration ensures the data is formatted correctly.
LifeMatch Birthday campaigns These campaigns rely on the LifeMatch process, which is currently only supported within flows.

⚠️ If you're using a platform not listed here and find that it doesn't support custom JSON bodies in API requests, you may need a middleware tool like Zapier to transform the payload into the format PostPilot requires. Contact our support team for guidance.

 

Key Differences: Flows vs. API Segments

Concept Flows API Segments
API endpoints Each flow has a unique trigger URL One shared set of endpoints for all campaigns
Design assignment Design is tied directly to the flow's send block Design is set on the campaign; segments determine who receives it
Multiple campaigns Requires multiple flows with unique URLs Use custom fields to differentiate; filter segments accordingly
A/B testing & holdouts Require separate flows; limited cross-group comparison Configured on the campaign with direct comparison across variants
MailMatch support Not supported Supported via api_email_contact endpoint

 

API Endpoint Examples

Below are the full JSON body examples for each endpoint, showing all available fields. Use these as a reference when configuring your API calls.

Create/Update API Full Contact:

POST api.postpilot.com/v1/{connection_id}/api_full_contact
{
  "reference_id": "customer_123",
  "email":        "customer@example.com",
  "fullname":     "John Doe",
  "firstname":    "John",
  "lastname":     "Doe",
  "line1":        "123 Main St",
  "line2":        "Apt 4",
  "city":         "New York",
  "state":        "NY",
  "postal_code":  "10001",
  "country":      "US",
  "custom_1":     "",
  "custom_2":     "",
  "custom_3":     ""
}

Create/Update API Email Contact (MailMatch™):

POST api.postpilot.com/v1/{connection_id}/api_email_contact
{
  "email":    "customer@example.com",
  "fullname": "John Doe",
  "custom_1": "",
  "custom_2": "",
  "custom_3": ""
}

Shopify Customer Event:

POST api.postpilot.com/v1/{connection_id}/shopify_customer_event
{
  "email":       "customer@example.com",
  "customer_id": "123456789",
  "custom_1":    "",
  "custom_2":    "",
  "custom_3":    ""
}