How do I integrate Identity Management with Piano ESP?

Identity Management and Piano ESP are separate products, and there is no automatic, out-of-the-box data sync that pushes Identity Management profile attributes (such as first name) into ESP mailing lists. Instead, integration is built on two complementary mechanisms:

• ESP subscribe/unsubscribe API calls triggered by your registration, login, or profile-update flows, optionally combined with user merge fields to carry profile data into ESP.

• ESP-to-publisher callbacks (webhooks) that notify your back-end whenever a user is subscribed or unsubscribed in ESP, so you can keep Identity Management (or your own user store) in sync in the opposite direction.

The same pattern applies whether you use Identity Management, Identity Linking, or a fully custom identity system: ESP exposes API endpoints for managing subscribers, and your identity layer is responsible for calling them.

When to use ESP API vs. Identity Management handlebars

Identity Management can render handlebar tokens in its own transactional emails. ESP does not read Identity Management profile fields directly; instead, you populate ESP user merge fields through the ESP API at subscription time (or via a later update call), and reference those merge fields in your ESP templates. If you need a customer's first name (or any other Identity Management attribute) inside an ESP campaign, push it into a merge field through the API rather than expecting ESP to look it up.

Subscribing users from a registration or login flow

When a new free member registers (or an existing user opts in), call the ESP subscribe endpoint to add them to one or more mailing lists. The base call is an HTTP POST to:

http(s)://api-esp.piano.io/tracker/securesub?api_key=<api_key>

with either application/x-www-form-urlencoded or application/json body containing the user's email and the target mlids (mailing-list IDs).

A few practical recommendations when wiring registration to ESP:

• Keep separate mailing lists for distinct audiences. If you want to differentiate new free members from existing newsletter subscribers, provision a dedicated mailing list for free members and subscribe newly registered users to that list rather than the general newsletter list.

• Handle list moves explicitly. If an existing newsletter subscriber registers as a free member and you want them moved between lists, issue both an HTTP DELETE (against the old list's mlid) and a POST (against the new list's mlid).

• Watch for shared addresses across lists. A campaign attached to multiple mailing lists will only send one email per unique address. Conversely, when a user clicks the ESP unsubscribe link, they are unsubscribed from every mailing list attached to that campaign, regardless of how many lists contained the address.

Identity Linking integration

Clients using Identity Linking (rather than Identity Management) do not have a direct "subscribe to ESP" hook from the identity layer. They must call the ESP subscriber API themselves. The endpoints and payloads are identical to the Identity Management case; what changes is where in your stack the call is made — typically a server-side handler attached to Identity Linking registration, profile updates, and account deletion events.

ESP-to-publisher callbacks (the inverse direction)

To keep Identity Management (or any other user store) up to date with subscription activity that originates inside ESP — for example, users who click the unsubscribe link in an email — register an HTTPS callback with Piano ESP. ESP will then POST JSON to your endpoint whenever a relevant subscription event occurs.

Configuration details you need to provide

When asking your Piano contact to register a callback URL, supply:

• Site ID(s): the numeric ESP Site ID (or IDs) that the callback should serve.

• Environment: Sandbox, US-Prod, EU-Prod, or AP-Prod. Each environment is managed independently; configure separate endpoints for sandbox and production.

• Event scope: user_added (new subscriptions), user_removed (unsubscriptions), or both.

• Security settings: any URL token or custom header you want ESP to include, plus any ESP IP ranges that need to be whitelisted by your firewall.

• Port: only relevant if your endpoint listens on something other than 443 over HTTPS.

Endpoint requirements

Your endpoint must:

• Accept POST requests with Content-Type: application/json.

• Parse a payload of the form:

  { "email": "user@example.com", "sqid": <mailing_list_id>, "action": "user_added" }
  

  where action is either user_added or user_removed.

• Return an HTTP 2xx status within a few seconds. Seven consecutive non-2xx responses will automatically suspend the webhook.

• For lists configured with Double Opt-In, expect the callback to fire only after the user completes the confirmation step.

If multiple downstream systems need to consume these events, place an API gateway or proxy in front of the callback URL — ESP delivers each event to a single endpoint.

Linking callbacks back into Identity Management

On callback receipt, look up the user in Identity Management by email. If the user exists, update their profile (for example, persist the sqid they subscribed to, or flag them as a newsletter subscriber). If they do not exist, you can create a new Identity Management user, optionally with a password-less flag, so future logins resolve to the same identity.

Testing

Before going live, exercise the callback in sandbox by triggering a real subscribe and unsubscribe in the ESP dashboard (or by curl-ing the appropriate ESP API), and confirm your server logs show a 2xx response with the expected payload. Once that round-trip is clean, promote the configuration to production.

Cross-app user access checks

If your Piano setup spans multiple apps and you need to verify that a user has access in any one of them, use:

/publisher/user/access/check

with the cross_app parameter set to true. The endpoint will resolve access without requiring the user to have been explicitly created in each app first. The PianoComposer SDK creates users in an app the first time they hit access-protected content; if you need an account ahead of that touchpoint, create the user via the API.

Custom opt-in forms (web and mobile)

When you build your own opt-in forms — whether in a web flow, a mobile app, or anywhere else — you replace the Piano ESP opt-in widget with calls to the ESP subscriber API. For email templates that need to render personalized "Manage Subscriptions" links, ESP exposes the %SUBSCRIBERINFO% merge field, which is replaced at send time with a Base64-encoded JSON object describing the subscriber. Your custom subscribe/unsubscribe page decodes this payload and uses it to call the ESP API on the user's behalf. See the related guide on custom subscription / unsubscribe landing pages for the full pattern.

The same approach works for mobile apps: build a native "Manage Subscriptions" screen that decodes %SUBSCRIBERINFO% from a deep-link parameter and drives ESP subscribe/unsubscribe API calls from the app's back-end.

Troubleshooting

• Callback "action" looks wrong. Re-verify which HTTP method and path your endpoint is configured for, and that the same URL is not being reused across event scopes.

• Callback stops firing. Check whether seven consecutive non-2xx responses have suspended the webhook; if so, fix the endpoint and ask Piano to re-enable it.

• Users appear in Identity Management but never in ESP. Confirm your registration handler is actually calling the ESP securesub POST, with a valid api_key for the correct environment, and that the mlids exist on that site.

• Merge fields are empty in ESP campaigns. Verify that the merge field exists in the ESP dashboard for the relevant site and that you are setting it via the merge-field API (/userdata/umfval/...) at or after subscription — non-existent merge fields will cause API errors rather than being silently created.

Last updated: July 03, 2026