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


---

# 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/lists.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.