API-Triggered Segments & MailMatch via API

📌 Flows are being deprecated. All new API-driven campaigns — including Klaviyo, Recharge, and other integrations — should be built as segments going forward. This article covers the new approach.

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 flow is the same: your external system fires a webhook to one of these endpoints, PostPilot updates the contact record, and an automated 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.

Go to Integrations → API Connection
Click Manage under the API Connection card
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 webhook 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/****837f/api_email_contact

Example JSON body for Klaviyo:

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

Step 2: Create the segment and campaign in PostPilot

Go to Segments → New Segment
Select the API Contacts with Email target
Add a Contact updated date (relative) filter set to on or after 2 days ago to ensure only recently triggered contacts are included
Create and launch an 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 automated 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 webhook 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/****837f/api_full_contact

Example JSON body for Klaviyo:

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

Step 2: Create the segment and campaign in PostPilot

Go to Segments → New Segment
Select API Contacts with Address
Optionally add a Contact updated date (relative) filter to target only recently triggered contacts
Create an automated campaign targeting this segment

Shopify Customer Events via API

This endpoint lets you fire a postcard send to an existing Shopify customer by triggering an event via webhook — without needing to pass a full address.

Step 1: Configure the webhook in your external platform

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

POST api.postpilot.com/v1/****837f/shopify_customer_event

The JSON body only requires an email or customer ID:

{
  "email": "john.q.customer@gmail.com"
}

Step 2: Create the segment and campaign in PostPilot

Go to Segments → New Segment and create a Shopify customer segment
Add an API Shopify customer event occurred (relative) filter
Set the time window (e.g., on or after 2 days ago)
Create an 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 webhook 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)

Create an equivalent segment targeting API Full Contacts (or Shopify customers), filtered by recently updated contacts
Create an automated campaign targeting that segment with the same postcard design
Turn off the old flow
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 webhook setup to use custom fields for differentiation:

Update each webhook in your external system to call the single api_full_contact endpoint, adding a custom_1 value that identifies the event (e.g., "purchased" or "no_purchase")
Create a separate segment in PostPilot for each event type, filtering by the corresponding custom field value
Set up a dedicated automated 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 Endpoints Reference

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":    ""
}