> For the complete documentation index, see [llms.txt](https://humanic.gitbook.io/humanic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://humanic.gitbook.io/humanic/campaigns/managing-unsubscribed-users.md).

# Managing unsubscribed users

Organizations often employ various tools to connect with customers over time. Although these tools facilitate managing unsubscribes from mailing lists, their effectiveness is confined to each specific tool. Consequently, if you transition to a new tool for customer outreach, previously unsubscribed customers may still receive emails. Ideally, regardless of the tool used, customer unsubscribe requests should be respected.

We allow you to sync your unsubscription list across tools. By using our APIs you will be able to do the following:

* Upload the list of emails that have unsubscribed through other tools.
* Get list of unsubscribed users that have unsubscribed on our platform.
* Remove emails from unsubscribed list.
* Associate tags with emails to selectively opt out users from specific campaigns and sequences. 

### API Endpoints

## Get Unsubscribed Emails

<mark style="color:blue;">`GET`</mark> `https://backend.humanic.ai/v1/unsubscribed_emails/`

#### Query Parameters

| Name  | Type    | Description                                        |
| ----- | ------- | -------------------------------------------------- |
| limit | Integer | No of results in a respose (default: 10; max: 100) |
| skip  | Integer | No of results to offset (default: 0)               |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "total": 125,
    "items": [
        {"email": "abc@xyz.co", "source": "humanic", "tags": ["t1", "t2"]},
        {"email": "xyz@abc.co", "source": "api", "tags": []}
    ]
}
```

{% endtab %}
{% endtabs %}

## Create Unsubscribed Emails

<mark style="color:green;">`POST`</mark> `https://backend.humanic.ai/v1/unsubscribed_emails/`

If the email is already in the unsubscribed list, tags will be updated.&#x20;

If the "source" is not specified for any email, it defaults to "api".

Source should only contain alphanumeric characters, underscores(\_) or periods(.)

Tag should only contain alphanumeric characters, underscores(\_), periods(.), or an asterisk(\*)

Tags can be used to selectively unsubscribe users from particular sequences (tags are matched with sequence's tags)

#### Request Body

| Name                                    | Type  | Description                                                |
| --------------------------------------- | ----- | ---------------------------------------------------------- |
| items<mark style="color:red;">\*</mark> | Array | \[{"email": "<xyz@abc.co>", "source": "api", "tags": \[]}] |

{% tabs %}
{% tab title="200: OK "msg" containing info about the no of entries created and updated" %}

```json
{
    "total": 125,
    "items": [
        {"email": "abc@xyz.co", "source": "humanic", "tags": ["t1", "t2"]},
        {"email": "xyz@abc.co", "source": "api", "tags": []}
    ]
}
```

{% endtab %}
{% endtabs %}

## Delete Unsubscribed Emails

<mark style="color:red;">`DELETE`</mark> `https://backend.humanic.ai/v1/unsubscribed_emails/`

#### Request Body

| Name                                    | Type  | Description                  |
| --------------------------------------- | ----- | ---------------------------- |
| items<mark style="color:red;">\*</mark> | Array | \[{"email": "<xyz@abc.co>"}] |

{% tabs %}
{% tab title="200: OK "msg" containing info about the no of entries deleted" %}

```json
{
    "total": 125,
    "items": [
        {"email": "abc@xyz.co", "source": "humanic", "tags": ["t1", "t2"]},
        {"email": "xyz@abc.co", "source": "api", "tags": []}
    ]
}
```

{% endtab %}
{% endtabs %}

#### Authentication

Get API Key from [here](https://dashboard.humanic.ai/dashboard/profile/?tab=API+Key) and pass it as "Authorization" header as Basic token.

```
Authorization: Basic <YOUR_API_KEY>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://humanic.gitbook.io/humanic/campaigns/managing-unsubscribed-users.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.