# Lists

## Get lists

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

Gets all AcyMailing lists or lists by ID

#### Query Parameters

| Name    | Type  | Description                                                                                                                                                                                                     |
| ------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.                                                                                                                                             |
| filters | Array | <p>You can filter users by column value. For example the id, active status or confirmation status. Available filters:</p><p>\[</p><p>    "id": 421,</p><p>    "name": "test",</p><p>    "active": 0</p><p>]</p> |

#### 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 lists or an empty array." %}

```json
[
    [
        {
            "id": "1",
            "name": "Newsletters",
            "display_name": null,
            "active": "1",
            "visible": "1",
            "clean": null,
            "color": "#3366ff",
            "creation_date": "2023-07-19 13:44:07",
            "welcome_id": "26",
            "unsubscribe_id": null,
            "cms_user_id": "1",
            "access": "",
            "description": "",
            "tracking": "1",
            "type": "standard",
            "translation": ""
        },
        {
            "id": "19",
            "name": "Testing list",
            "display_name": null,
            "active": "1",
            "visible": "0",
            "clean": null,
            "color": "#94d4a6",
            "creation_date": "2024-01-15 09:52:10",
            "welcome_id": null,
            "unsubscribe_id": null,
            "cms_user_id": "1",
            "access": "",
            "description": "",
            "tracking": "1",
            "type": "standard",
            "translation": ""
        }
    ]
]
```

{% endtab %}
{% endtabs %}

## Create a list

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

The parameters must be sent in JSON format inside the request's body.

#### 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                                                                                                                                                                      |
| -------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | String | The name of the new list                                                                                                                                                         |
| active                                 | Int    | <p>Defaults to 1.</p><p>1 = list active</p><p>2 = list inactive</p>                                                                                                              |
| color                                  | String | The hexadecimal color code. For example #3366ff                                                                                                                                  |
| welcomeId                              | Int    | The ID of the AcyMailing mail to send when a user subscribes to this list.                                                                                                       |
| unsubscribeId                          | Int    | The ID of the AcyMailing mail to send when a user unsubscribes from this list.                                                                                                   |
| visible                                | Int    | <p>Defaults to 1.</p><p>1 = list visible</p><p>2 = list invisible</p><p></p><p>An invisible list won't be shown on subscription forms. These are generally management lists.</p> |

{% tabs %}
{% tab title="422: Unprocessable Entity List name is missing" %}

```json
{
    "message": "List name missing."
}
```

{% endtab %}

{% tab title="201: Created List created" %}

```json
{
    "listId": 20
}
```

{% endtab %}

{% tab title="500: Internal Server Error An error occurred" %}

```
{
    "message": "Error creating list.",
    "errors": [...]
}
```

{% endtab %}
{% endtabs %}

## Delete a list

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

This deletes an AcyMailing list

#### Query Parameters

| Name                                     | Type | Description                                           |
| ---------------------------------------- | ---- | ----------------------------------------------------- |
| listId<mark style="color:red;">\*</mark> | Int  | The ID corresponding to the AcyMailing list to delete |

#### 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 Deletion went well" %}

```json
{
    "message": "List deleted."
}
```

{% endtab %}

{% tab title="500: Internal Server Error An error occurred" %}

```json
{
    "message": "Error deleting list."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The list id is missing" %}

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

{% endtab %}

{% tab title="404: Not Found List not found" %}

```
{
    "message": "List not found."
}
```

{% endtab %}
{% endtabs %}