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