The Email Unsubscribe API allows you to ingest email addresses into either the global unsubscribe list or a specific unsubscribe group you created in InOne.
The Email Unsubscribe API v2 is the latest version of the Email Unsubscribe API, which supports bulk data ingestion. If you're still using the previous version (v1), we strongly recommend migrating to the updated version to take advantage of bulk updates and enhanced functionality. Please note that new integrations with v1 are no longer supported.
API usage varies depending on the identifier format you use. Please refer to the relevant section based on your identifier configuration.
Endpoint and Headers
Visit our Postman collection to test this request.
Headers
Header | Sample Value | Description |
|---|---|---|
X-PARTNER-NAME | mybrand | This is your partner name. Navigate to InOne > Inone Settings > Account Settings to copy your partner name. The partner name should be lowercase. |
X-REQUEST-TOKEN | 1a2b3c4e5d6f | This key is required to authorize your request. Refer to API Authentication Tokens to generate your Global Unsubscribe token. |
Content-Type | application/json | This header specifies the media type of the resource. |
Body Parameters
For Email Global Unsubscribe
Parameter | Description | Data Type | Required |
|---|---|---|---|
emails | User's email addresses | String Array | Yes (normal and email-based) |
uuids | User's unique user identifier | String Array | Yes (only if you are not using email as an identifier and using profile-based) |
For Email Group Unsubscribe
Parameter | Description | Data Type | Required |
|---|---|---|---|
emails | Users' email addresses | String Array | Yes |
users | Users' unique user identifier | String Array | Yes (only if you are not using email as an identifier) |
group_name | The Unsubscribe Group’s name. If the group name does not exist, it creates a new group and unsubscribes the user from it. More than two, fewer than 30 characters. | String | Yes |
Sample Requests
When Email is the Identifier or Email-Based Flow is Enabled
Unsubscribe Users
The sample below shows a request to unsubscribe multiple users globally via email.
Every request to the request endpoint must include a JSON-formatted body containing your email's content and metadata.
When email is used as the identifier:
If the user exists, their status is updated.
If the user does not exist, a new user is created.
In the email-based flow, the same request updates only the status of existing users and does not create new ones.
The emails field is required for global unsubscribe requests.
curl --location 'contact.useinsider.com/email/v2/unsubscribe' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: a1b2c3d4e5f6' \
--header 'Content-Type: application/json' \
--data-raw '{
"emails": [
"sample1@useinsider.com",
"sample2@useinsider.com",
"sample3@useinsider.com"
]
}'Unsubscribe Users from Unsubscribe Groups
The sample below displays a request to unsubscribe users from a specific unsubscribe group.
In cases where the email is used as the identifier, if the user exists, their status will be updated; if the user does not exist, a new user will be created.
For the email-based flow, the same request is used; however, it updates only the status of existing users and does not create new users.
emails and group_name fields are required for the group unsubscribe requests.
If the group name you provided does not already exist, a new group will be created with that name when the request is sent.
curl --location 'contact.useinsider.com/email/v2/unsubscribe' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: a1b2c3d4e5f6' \
--header 'Content-Type: application/json' \
--data-raw '{
"emails": [
"sample1@useinsider.com",
"sample2@useinsider.com",
"sample3@useinsider.com",
"sample4@useinsider.com",
"sample5@useinsider.com"
],
"group_name": "unsubscribe_group_name"
}'When UUID is the Identifier and Profile-Based Flow is Enabled
Unsubscribe Users
The sample below displays a request to unsubscribe users when the UUID is the identifier and profile-based flow is enabled.
Every request made to the request endpoint requires a request body formatted in JSON and containing your email's content and metadata.
If the profile-based flow is enabled for your account,
If the user in the request exists, their status will be updated.
If the user does not exist, a new user will be created.
uuid and email fields are required for global unsubscribe requests.
curl --location 'http://contact.useinsider.com/email/v2/unsubscribe' \
--header 'Content-Type: application/json' \
--header 'x-request-token: a1b2c3d4e5f6' \
--header 'x-partner-name: mybrand' \
--data-raw '{
"users": [
{
"uuid": "test-uuid-1",
"email": "sample1@useinsider.com"
},
{
"uuid": "test-uuid-2",
"email": "sample2@useinsider.com"
},
{
"uuid": "test-uuid-3",
"email": "sample3@useinsider.com"
},
{
"uuid": "test-uuid-4",
"email": "sample4@useinsider.com"
}
]
}'Unsubscribe Users from Unsubscribe Groups
The sample below displays a request to unsubscribe users from a specific unsubscribe group when the UUID is used as the identifier.
email, uuid, and group_name fields are required for the group unsubscribe requests.
If the group name you provided does not already exist, a new group will be created with that name when the request is sent.
curl --location 'http://contact.useinsider.com/email/v2/unsubscribe' \
--header 'Content-Type: application/json' \
--header 'x-request-token: a1b2c3d4e5f6' \
--header 'x-partner-name: mybrand' \
--data-raw '{
"users": [
{
"uuid": "test-uuid-1",
"email": "sample1@useinsider.com"
},
{
"uuid": "test-uuid-2",
"email": "sample2@useinsider.com"
},
{
"uuid": "test-uuid-3",
"email": "sample3@useinsider.com"
},
{
"uuid": "test-uuid-4",
"email": "sample4@useinsider.com"
}
]
"group_name": "group_name"
}'Sample Responses
200 OK
{
"statusMessage": "OK"
}400 Bad Request
{
"statusMessage": "Bad request"
}401 Unauthorized
{
"statusMessage": "Unauthorized"
}Limitations
All functions must be executed with a simple HTTPS POST request.
A maximum of 500 emails or UUIDs can be consumed in one request.
The API Key should be provided as the authorization key in the request header. If the key is incorrect, the operation will not be executed, and an authorization error will return in the response.
The value of X-PARTNER-NAME header should be lowercase.
The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team — we can adjust it to fit your needs.