# Subscription

## Get a user's subscriptions

<mark style="color:blue;">`GET`</mark> `https://www.example.com/index.php?page=acymailing_front&option=com_acym&ctrl=api&task=getUserSubscriptionById`

The subscription status will be returned for subscribed and unsubscribed lists.

#### Query Parameters

| Name                                     | Type | Description                   |
| ---------------------------------------- | ---- | ----------------------------- |
| userId<mark style="color:red;">\*</mark> | Int  | The ID of the AcyMailing user |

#### Headers

| Name                                      | Type   | Description                                                                                         |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Api-Key<mark style="color:red;">\*</mark> | String | The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License". |

{% tabs %}
{% tab title="422: Unprocessable Entity The user ID is missing" %}

```json
{
    "message": "User ID not provided in the query parameters."
}
```

{% endtab %}

{% tab title="200: OK The lists and subscription status. A status set to 1 means subscribed, and 0 means unsubscribed." %}

```json
[
    {
        "1": {
            "id": "1",
            "translation": "",
            "name": "Newsletters",
            "display_name": null,
            "color": "#3366ff",
            "active": "1",
            "visible": "1",
            "description": "",
            "status": "1",
            "subscription_date": "2023-07-21 09:17:06",
            "unsubscribe_date": null
        },
        "17": {
            "id": "17",
            "translation": "",
            "name": "N",
            "display_name": "",
            "color": "#5f702b",
            "active": "1",
            "visible": "1",
            "description": "",
            "status": "0",
            "subscription_date": "2024-01-16 10:58:05",
            "unsubscribe_date": "2024-01-16 16:27:13"
        },
        "19": {
            "id": "19",
            "translation": "",
            "name": "Testing list",
            "display_name": null,
            "color": "#94d4a6",
            "active": "1",
            "visible": "0",
            "description": "",
            "status": "1",
            "subscription_date": "2024-01-15 09:52:10",
            "unsubscribe_date": null
        }
    }
]
```

{% endtab %}
{% endtabs %}

## Get subscribers of lists

<mark style="color:blue;">`GET`</mark> `https://www.example.com/index.php?page=acymailing_front&option=com_acym&ctrl=api&task=getSubscribersFromLists`

Returns the subscribers of specific lists

#### Query Parameters

| Name                                         | Type  | Description                                                                                                                |
| -------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
| listIds\[]<mark style="color:red;">\*</mark> | Array | <p>The IDs of the lists from which the subscribers are pulled. Example:</p><p>\[</p><p>    "1",</p><p>    "28"</p><p>]</p> |
| offset                                       | Int   | Defaults to 0. Used for pagination, skips the first X results.                                                             |
| limit                                        | Int   | Defaults to 100. Used for pagination, limits the number of results.                                                        |

#### Headers

| Name                                      | Type   | Description                                                                                         |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Api-Key<mark style="color:red;">\*</mark> | String | The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License". |

{% tabs %}
{% tab title="200: OK The matching users" %}

```json
[
    [
        {
            "email": "address@example.com",
            "name": "My name",
            "id": "1",
            "confirmed": "1",
            "status": "1",
            "subscription_date": "2023-07-21 09:17:06"
        },
        {
            "email": "address2@example.com",
            "name": "acytest",
            "id": "2",
            "confirmed": "1",
            "status": "1",
            "subscription_date": "2023-07-24 08:26:26"
        }
    ]
]
```

{% endtab %}

{% tab title="422: Unprocessable Entity The list IDs are missing." %}

```json
{
    "message": "List IDs not provided in the query parameters."
}
```

{% endtab %}
{% endtabs %}

## Get unsubscribed users of lists

<mark style="color:blue;">`GET`</mark> `https://www.example.com/index.php?page=acymailing_front&option=com_acym&ctrl=api&task=getUnsubscribedUsersFromLists`

Returns the AcyMailing users unsubscribed from specific lists

#### Query Parameters

| Name                                         | Type  | Description                                                                                                                |
| -------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
| listIds\[]<mark style="color:red;">\*</mark> | Array | <p>The IDs of the lists from which the subscribers are pulled. Example:</p><p>\[</p><p>    "1",</p><p>    "28"</p><p>]</p> |
| offset                                       | Int   | Defaults to 0. Used for pagination, skips the first X results.                                                             |
| limit                                        | Int   | Defaults to 100. Used for pagination, limits the number of results.                                                        |

#### Headers

| Name                                      | Type   | Description                                                                                         |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Api-Key<mark style="color:red;">\*</mark> | String | The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License". |

{% tabs %}
{% tab title="200: OK The matching users" %}

```json
[
    [
        {
            "email": "address@example.com",
            "name": "My name",
            "id": "4",
            "confirmed": "1",
            "status": "0",
            "subscription_date": "2023-10-04 09:54:43"
        },
        {
            "email": "address2@example.com",
            "name": "acytest",
            "id": "9",
            "confirmed": "1",
            "status": "0",
            "subscription_date": "2023-12-18 08:35:02"
        }
    ]
]
```

{% endtab %}

{% tab title="422: Unprocessable Entity The list IDs are missing." %}

```json
{
    "message": "List IDs not provided in the query parameters."
}
```

{% endtab %}
{% endtabs %}

## Subscribe users to lists

<mark style="color:green;">`POST`</mark> `https://www.example.com/index.php?page=acymailing_front&option=com_acym&ctrl=api&task=subscribeUsers`

Subscribe a list of users to one or more lists

#### Headers

| Name                                           | Type   | Description                                                                                         |
| ---------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Api-Key<mark style="color:red;">\*</mark>      | String | The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License". |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json                                                                                    |

#### Request Body

| Name                                         | Type  | Description                                                                                                                                                                                                           |
| -------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| emails\[]<mark style="color:red;">\*</mark>  | Array | <p>The email addresses of users to subscribe to the lists. These must match already existing AcyMailing users.<br>Example:</p><p>\[</p><p>    "<address@example.com>",</p><p>    "<address2@example.com>"</p><p>]</p> |
| listIds\[]<mark style="color:red;">\*</mark> | Array | <p>The IDs of the lists to which the users should be subscribed. Example:</p><p>\[</p><p>    "1",</p><p>    "28"</p><p>]</p>                                                                                          |
| sendWelcomeEmail                             | Bool  | <p>Defaults to true.</p><p>If true, the welcome emails will be sent if the lists have one.</p>                                                                                                                        |
| trigger                                      | Bool  | <p>Defaults to true.<br>If you want to trigger or not the automation or follow-up when subscribing the user.</p>                                                                                                      |

{% tabs %}
{% tab title="422: Unprocessable Entity A required parameter is missing" %}

```json
{
    "message": "Emails not provided in the request body."
}
```

```json
{
    "message": "List IDs not provided in the request body."
}
```

{% endtab %}

{% tab title="200: OK Subscription worked" %}

```json
{
    "message": "Users subscribed."
}
```

{% endtab %}

{% tab title="404: Not Found Some addresses did not match an existing user." %}
When this happens, it will correctly subscribe the found users and return the list of users not found.

```json
{
    "message": "Could not find some users.",
    "errors": [
        "test@example.com"
    ]
}
```

{% endtab %}
{% endtabs %}

## Unsubscribe users from lists

<mark style="color:green;">`POST`</mark> `https://www.example.com/index.php?page=acymailing_front&option=com_acym&ctrl=api&task=unsubscribeUsers`

Unsubscribe a list of users from one or more lists

#### Headers

| Name                                           | Type   | Description                                                                                         |
| ---------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Api-Key<mark style="color:red;">\*</mark>      | String | The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License". |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json                                                                                    |

#### Request Body

| Name                                         | Type  | Description                                                                                                                                                                                                               |
| -------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| emails\[]<mark style="color:red;">\*</mark>  | Array | <p>The email addresses of users to unsubscribe from the lists. These must match already existing AcyMailing users.<br>Example:</p><p>\[</p><p>    "<address@example.com>",</p><p>    "<address2@example.com>"</p><p>]</p> |
| listIds\[]<mark style="color:red;">\*</mark> | Array | <p>The IDs of the lists from which the users should be unsubscribed. Example:</p><p>\[</p><p>    "1",</p><p>    "28"</p><p>]</p>                                                                                          |
| sendUnsubscribeEmail                         | Bool  | <p>Defaults to true.</p><p>If true, the unsubscribe emails will be sent if the lists have one.</p>                                                                                                                        |
| trigger                                      | Bool  | <p>Defaults to true.<br>If you want to trigger or not the automation or follow-up when subscribing the user.</p>                                                                                                          |

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

```
{
    "message": "Users unsubscribed."
}
```

{% endtab %}

{% tab title="404: Not Found Some addresses did not match an existing user." %}

```
{
    "message": "Could not find some users.",
    "errors": [
        "test@example.com"
    ]
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity A required parameter is missing" %}

```json
{
    "message": "Emails not provided in the request body."
}
```

```json
{
    "message": "List IDs not provided in the request body."
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: 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:

```
GET https://docs.acymailing.com/rest-api/subscription.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.