Unsubscribe Email Users from Database / v2

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 this updated version to benefit from bulk updates and enhanced functionality. Please note that new integrations with v1 are no longer supported.

API usage changes depending on the identifier format you're using. Please refer to the relevant section based on your identifier configuration.

Endpoint and Headers

POST https://contact.useinsider.com/email/v2/unsubscribe

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 Preferences 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 displays a request to globally unsubscribe multiple users by email.

Every request made to the request endpoint requires a request body formatted in JSON and 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.
For the email-based flow, the same request only updates 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 will only update the status of existing users and will 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.