Operating on subscriber data in Echobox
This guide covers the Echobox endpoints for reading, updating, subscribing, unsubscribing and deleting subscriber data.
Summary
Echobox offers a range of endpoints for operating on subscriber data, allowing you to create, read, update and delete subscriber data, as well as allowing you to manage subscription statuses programmatically.
If you're looking to keep subscriber data in sync with an external system (like a CRM), see Synchronizing subscriber data with other systems, which builds on the endpoints described here.
Reading subscriber data
Get Subscriber
See documented endpoint here.
This endpoint returns all custom field data stored for a subscriber at the property level.
GET https://prod.cdp.service.echobox.com/v1/properties/{propertyURN}/customers/{email}
Response is a flat list of name/value pairs:
{
"data": [
{ "name": "First Name", "value": "John" },
{ "name": "Last Name", "value": "Doe" },
{ "name": "customField1", "value": "value1" }
]
}
Use this to retrieve a subscriber’s current data, or to check what fields already exist before an update.
This can also be used to display any data on a website account page in scenarios where a CRM or CDP is not used as the data storage for subscriber data.
Get subscriptions for a subscriber
See documented endpoint here.
This endpoint returns which campaigns a subscriber is subscribed to, and their engagement level for each.
GET https://prod.campaignapi.service.echobox.com/v1/properties/{propertyURN}/subscriptions/{email}
Example response:
{
"data": [
{ "campaignName": "Campaign 1", "campaignURN": "urn:newsletter:campaign:example1", "engagementLevel": "MEDIUM" },
{ "campaignName": "Campaign 2", "campaignURN": "urn:newsletter:campaign:example2", "engagementLevel": "HIGH" }
]
}
This endpoint is useful for building a subscription-status view in an external system or for returning and displaying active subscriptions on an account page.
Get subscriber journey status
See documented endpoint here.
This endpoint returns where a subscriber sits in any automation journeys (e.g. welcome series) running in the property.
GET https://prod.campaignapi.service.echobox.com/v1/properties/{propertyURN}/journeys/{email}
Example response:
{
"journeys": [
{
"journeyURN": "urn:newsletter:automationjourney:example",
"name": "Welcome Series",
"stages": [
{ "name": "Step 1", "numberOfCompletions": 1, "lastCompletionUnixTime": 1727740800 },
{ "name": "Step 2", "numberOfCompletions": 0, "lastCompletionUnixTime": null }
]
}
]
}
Useful for answering "where is this subscriber in their journey?".
Updating custom field data
Update Subscriber
See documented endpoint here.
This endpoint updates custom field data for one or more existing subscribers in a single call.
POST https://prod.cdp.service.echobox.com/v1/public/properties/{propertyURN}/manage-subscribers/integration
Example request payload:
{
"event": "update",
"subscribers": [
{
"email": "user1@example.com",
"customFields": {
"First Name": "John",
"Last Name": "Doe",
"field1": "value1",
"field2": "value2"
}
},
{
"email": "user2@example.com",
"customFields": {}
}
]
}
This endpoint is used most commonly when synchronizing subscriber data changes from a CRM or other system of record into Echobox. It updates existing subscribers; it doesn't handle subscription state (see below).
Managing subscriptions
There are three subscription-management endpoints, each suited to a different scope.
|
Endpoint |
Scope |
Subscribers per call |
Subscribe/Unsubscribe |
Use Case |
|---|---|---|---|---|
|
Subscribe/Unsubscribe From A Campaign |
Single campaign |
1 |
Subscribe or unsubscribe |
Sign-ups for a specific newsletter, or a single unsubscribe click routed through your own preference centre |
|
Manage Email Subscriptions For a Subscriber |
Single subscriber, multiple campaigns |
1 |
Subscribe and unsubscribe in one call |
A self-managed preference centre or account page |
|
Bulk Unsubscribe |
All campaigns across whole property |
Many |
Unsubscribe only |
Batch unsubscribe processes |
Subscribe/Unsubscribe from a campaign
See documented endpoint here.
POST https://prod.campaignapi.service.echobox.com/v1/public/campaigns/{campaignURN}/manage-subscribers/integration
Subscribe
Example request payload:
{
"event": "subscribe",
"email": "user@example.com",
"customFields": {
"First Name": "John",
"Last Name": "Doe",
"field1": "value1",
"field2": "value2"
}
}
Unsubscribe
Example request payload:
{
"event": "unsubscribe",
"email": "user@example.com"
}
This endpoint can be used for signups for a specific newsletter, or for an unsubscribe event routed through your own preference centre.
Manage subscriptions for a subscriber
See documented endpoint here.
POST https://prod.campaignapi.service.echobox.com/v1/properties/{propertyURN}/subscriptions/{email}
Example request payload:
{
"subscribeTo": ["urn:newsletter:campaign:example1"],
"unsubscribeFrom": ["urn:newsletter:campaign:example2"]
}
This endpoint can be used for a self-managed preference centre or account page where a subscriber manages multiple newsletter subscriptions at once e.g. they subscribe to "Weekly Digest" and unsubscribe from "Daily Alerts" in the same save action.
Bulk Unsubscribe
See documented endpoint here.
POST https://prod.campaignapi.service.echobox.com/v1/public/properties/{propertyURN}/manage-subscribers/integration
Example request payload:
{
"event": "unsubscribe",
"subscribers": [
{ "email": "user1@example.com" },
{ "email": "user2@example.com" }
]
}
This endpoint should be used with caution. It can be used to process a batch of unsubscribes property-wide (e.g. after a list-cleaning exercise). Unsubscribed subscribers still appear in reporting as unsubscribed, this does not delete them.
Deleting subscribers
Bulk Delete Subscribers
See documented endpoint here.
DELETE https://prod.campaignapi.service.echobox.com/v1/properties/{propertyURN}/subscribers
Example request payload:
{
"emails": ["example@email.com", "another@email.com"],
"isRightToBeForgotten": false
}
The isRightToBeForgotten flag controls the severity of the deletion:
|
isRightToBeForgotten |
Effect |
Appears in unsubscribe-rate reporting? |
|---|---|---|
|
false (default) |
Removes the subscriber, retains bounce history only |
No |
|
true |
Irreversibly deletes all data associated with the subscriber, including bounce history |
No |
Use isRightToBeForgotten: true sparingly. It's designed for GDPR "right to be forgotten" requests specifically. Because it also deletes bounce data, using it outside that context can damage your sender reputation and deliverability. Echobox uses bounce history to protect your domain from repeatedly emailing invalid addresses. If you just want someone to stop receiving emails and to reflect that in your unsubscribe reporting, use the unsubscribe endpoints above instead.
What's the difference between the bulk delete endpoint and bulk unsubscribe endpoint?
The Bulk Unsubscribe endpoint keeps the subscriber's record intact and marks them as unsubscribed. They still show up in your reporting and it counts toward your unsubscribe rate.
The Bulk Delete endpoint, with isRightToBeForgotten: “false” removes the subscriber record itself. They vanish from subscription reporting entirely and do not show as unsubscribed.. Bounce history is retained (so Echobox can still protect your sending reputation), but everything else tied to that subscriber record is not.