# Users

## Get users

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

Gets AcyMailing users based on optional criteria

#### 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>    "cms\_id": 828,</p><p>    "email": "<address@example.com>",</p><p>    "active": 1</p><p>    "confirmed": 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 list of found users or an empty array" %}

```json
[
    {
        "id": "1",
        "name": "The user name",
        "email": "address@example.com",
        "creation_date": "2023-07-19 13:44:08",
        "active": "1",
        "cms_id": "1",
        "source": null,
        "confirmed": "1",
        "key": "doZaVzX4jQezQf",
        "automation": "",
        "confirmation_date": null,
        "confirmation_ip": null,
        "tracking": "1",
        "language": "en-US",
        "last_sent_date": "2024-01-05 15:57:41",
        "last_open_date": "2023-10-04 12:17:48",
        "last_click_date": null
    }
]
```

{% endtab %}
{% endtabs %}

## Create or update a user

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

Add a new AcyMailing user or update an existing one

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

{% hint style="info" %}
If you want to update the language column you'll have to do it like a custom field because it is a custom field that is now "mandatory"
{% endhint %}

#### Request Body

| Name                                    | Type   | Description                                                                                                                                                                                         |
| --------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| email<mark style="color:red;">\*</mark> | String | The email address is used when updating an existing user                                                                                                                                            |
| name                                    | String | Any character should be available                                                                                                                                                                   |
| active                                  | Int    | <p>Defaults to 1.<br>1 = user active</p><p>0 = user inactive</p>                                                                                                                                    |
| confirmed                               | Int    | <p>Defaults to 0.</p><p>1 = user confirmed</p><p>0 = user not confirmed</p><p></p><p>The confirmation is related to the "Require confirmation" option in the configuration, tab "Subscription".</p> |
| cms\_id                                 | Int    | <p>Defaults to 0.</p><p>The cms\_id must match the ID of the corresponding Joomla/WordPress user.</p>                                                                                               |
| customFields                            | Array  | <p>Must be couples of field IDs and values. For example:</p><p>\[</p><p>    "3": "My value",</p><p>    "5": \[</p><p>        "one",</p><p>        "two"</p><p>    ]</p><p>]</p>                     |
| triggers                                | Bool   | Defaults to true. Defines if the saving of the user triggers automated tasks like follow-up campaigns and automations.                                                                              |
| sendConf                                | Bool   | Defaults to true. Defines if the confirmation email should be sent when a new user is created.                                                                                                      |

{% tabs %}
{% tab title="201: Created When the user has been created/updated" %}

```json
{
    "userId": 21
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The email address is missing" %}

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

{% endtab %}

{% tab title="500: Internal Server Error An error occurred when creating/updating the user" %}

```json
{
    "message": "Error saving user.",
    "errors": [
        "Please enter a valid e-mail address"
    ]
}
```

{% endtab %}
{% endtabs %}

## Delete a user

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

This deletes an AcyMailing user by email or ID

#### Query Parameters

| Name   | Type   | Description                                                                                                |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| email  | String | The email address corresponding to the AcyMailing user to delete. Required if the ID parameter is missing. |
| userId | Int    | The ID corresponding to the AcyMailing user 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": "User deleted."
}
```

{% endtab %}

{% tab title="404: Not Found When the searched user was not found" %}

```json
{
    "message": "User not found."
}
```

{% endtab %}

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

```json
{
    "message": "Email or user ID not provided in query parameters."
}
```

{% endtab %}

{% tab title="500: Internal Server Error When an error occurs during deletion" %}

```
{
    "message": "Error deleting user.",
    "errors": [...]
}
```

{% 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/users.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.