How Do I Unsubscribe Users from Piano ESP Mailing Lists via API?

When to use the API instead of the unsubscribe link

Every ESP email includes a Piano ESP-generated unsubscribe link. The link works without integration — clicking it unsubscribes the user from the campaign and from every mailing list attached to it.

Use the unsubscribe API when you want to:

• Process unsubscribes from your own form or preferences page (without relying on the per-user signature sig=... that the email link uses).

• Synchronize unsubscribe state from another system into ESP — for example, when a user revokes consent in an upstream consent tool, when their Management + Billing subscription ends, or when access is revoked.

• Unsubscribe a user from one specific mailing list while keeping them subscribed to others on the same site.

Within the ESP interface, customer-service agents can also remove a user from a specific mailing list by hovering over the list in the user's record and selecting the remove action; this does not require API access and removes only the targeted list.

The unsubscribe endpoint

Issue an HTTP DELETE to:

DELETE https://api-esp.piano.io/tracker/securesub?api_key=<api_key>

Set Content-Type: application/json and pass:

{
  "email": "<reader_email>",
  "mlids": [ idX, idY, ... ]
}

mlids is the list of mailing list IDs to unsubscribe the user from. The same endpoint accepts application/x-www-form-urlencoded, in which case mlids is a comma-separated string.

Base URLs by environment and region:

The API key authenticates the call. See How Do I Generate and Manage Piano ESP API Keys? for how to obtain one; the key must match the environment and the Site whose mailing lists you are addressing.

If you receive 405 Method Not Allowed, verify that you are using DELETE (not POST) and that the URL is exactly tracker/securesub. If you receive Bad ID(s), the supplied mlids do not exist for the Site whose API key you used.

Single list vs. all lists

The endpoint unsubscribes the user from the mailing list IDs you supply. To remove a user from one list without affecting others, pass only that one mlid. To remove them from a campaign entirely, pass every mlid attached to the campaign — or use the in-email unsubscribe link, which unsubscribes from the campaign and from every mailing list attached to it in one action.

What "unsubscribed" means: subscription statuses

When a user is removed via the API, their record stays in the audience and their status on the affected mailing list becomes 0 (inactive). Other status values reflect different causes of removal:

An inactive user (0) does not receive emails on that list. Users with hard-bounce or spam statuses (-2, -3, -9) are not resubscribable through the regular API path — they require a Piano Support ticket after the underlying email-deliverability cause is resolved.

You can check a user's current status with the subscription status query:

GET https://api-esp.piano.io/tracker/securesub/email/<email>/ml/<mailing_list_id>?api_key=<api_key>

HTTP 200 means the user is currently subscribed; HTTP 404 means they are not, and the response message includes the underlying status if the user was previously known.

The unsubscribe callback

When a user unsubscribes — whether through the in-email link or through any other route ESP knows about — ESP can notify a registered HTTPS endpoint with a JSON event:

{
  "email": "<reader_email>",
  "sqid": <mailing_list_id>,
  "action": "user_removed"
}

• email — the user's email address.

• sqid — the mailing list ID (historically called "squad ID" inside ESP).

• action — for unsubscriptions, the value is user_removed.

To register an endpoint to receive these events, contact your Account Manager or Piano Support and supply the endpoint URL and the Site. The endpoint should accept POST requests with Content-Type: application/json and return a 2xx response within a few seconds.

A user's unsubscription from a campaign triggers simultaneous unsubscription from every mailing list attached to that campaign — and emits a user_removed event for each affected mailing list.

Common patterns

Replacing your own unsubscribe link

To run your own unsubscribe page (instead of using the per-email signed link), build a form that captures the user's email, then have your server call the unsubscribe endpoint with that email and the relevant mlids. The API path does not require the per-user sig=... signature that the email link uses, so the same backend can process unsubscribes coming from multiple places — including other ESPs, consent tools, or your account UI.

Automated unsubscribe when access ends

To unsubscribe users automatically when their subscription or access in another system ends:

1. Configure Management + Billing webhooks (or another upstream signal) to notify your server on events such as access_revoked and subscription_ended.

2. On receipt, call the ESP unsubscribe endpoint with the affected user's email and the relevant mlids.

3. Optionally run a nightly reconciliation job comparing current access state to ESP list membership to catch dropped events.

Pair this with the subscribe-on-access-granted side of the workflow so the two stay aligned.

Bulk unsubscribing without deleting history

To disable mailing-list subscriptions for a set of users without losing their historical engagement data, iterate over the user list and call the unsubscribe endpoint for each email and the relevant mlids. This preserves the user record and engagement history while taking them off the list — preferable to deleting the user, which removes their behavioural data.

Unsubscribing one user from one list, programmatically

Pass exactly one mlid in the request body. Other mailing lists the user is on are unaffected.

Why a user might be unsubscribed

A user record can land in status 0 for several reasons. Understanding which one applies governs whether and how they can be resubscribed:

• Hard bounce. Their email address could not be delivered; status is -2 (or -3 / -9 for related deliverability problems). They are auto-unsubscribed.

• Spam complaint. They marked an email as spam; status -3.

• In-email unsubscribe link. They clicked the link in a received email; status 0 for every list attached to the campaign.

• API call. Your integration (or a third-party consent tool) issued a DELETE to tracker/securesub; status 0 for the supplied mlids.

Hard bounces and API-driven unsubscribes are logged separately, and both can affect campaign statistics. If a user appears unsubscribed unexpectedly, check both the unsubscribe events and the bounce log to determine the cause.

What happens after the unsubscribe

• The user remains in the ESP audience with status 0 for the affected lists. They are not deleted; their engagement history is preserved.

• The user's record can be queried, updated, or re-added to other lists they are not on — but a subsequent subscribe call for the same list will not silently flip them back to active if they unsubscribed via the in-email link. They must re-opt-in through a subscription flow themselves.

• If you need to clear a status on a user record (for example, to reset a 0 you set in error), escalate to Piano Support.

Last updated: July 02, 2026