# 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 %}