Subscription

This section shows the available routes related to subscriptions of AcyMailing users to lists.

Get a user's subscriptions

GET 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*	Int	The ID of the AcyMailing user

Headers

Name	Type	Description
Api-Key*	String	The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License".

422: Unprocessable Entity The user ID is missing

{
    "message": "User ID not provided in the query parameters."
}

200: OK The lists and subscription status. A status set to 1 means subscribed, and 0 means unsubscribed.

[
    {
        "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
        }
    }
]

Get subscribers of lists

GET 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[]*	Array	The IDs of the lists from which the subscribers are pulled. Example: [ "1", "28" ]
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*	String	The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License".

200: OK The matching users

[
    [
        {
            "email": "[e-mail]",
            "name": "My name",
            "id": "1",
            "confirmed": "1",
            "status": "1",
            "subscription_date": "2023-07-21 09:17:06"
        },
        {
            "email": "[e-mail]",
            "name": "acytest",
            "id": "2",
            "confirmed": "1",
            "status": "1",
            "subscription_date": "2023-07-24 08:26:26"
        }
    ]
]

422: Unprocessable Entity The list IDs are missing.

{
    "message": "List IDs not provided in the query parameters."
}

Get unsubscribed users of lists

GET 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[]*	Array	The IDs of the lists from which the subscribers are pulled. Example: [ "1", "28" ]
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*	String	The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License".

200: OK The matching users

[
    [
        {
            "email": "[e-mail]",
            "name": "My name",
            "id": "4",
            "confirmed": "1",
            "status": "0",
            "subscription_date": "2023-10-04 09:54:43"
        },
        {
            "email": "[e-mail]",
            "name": "acytest",
            "id": "9",
            "confirmed": "1",
            "status": "0",
            "subscription_date": "2023-12-18 08:35:02"
        }
    ]
]

422: Unprocessable Entity The list IDs are missing.

{
    "message": "List IDs not provided in the query parameters."
}

Subscribe users to lists

POST 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*	String	The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License".
Content-Type*	String	application/json

Request Body

Name	Type	Description
emails[]*	Array	The email addresses of users to subscribe to the lists. These must match already existing AcyMailing users. Example: [ "[e-mail]", "[e-mail]" ]
listIds[]*	Array	The IDs of the lists to which the users should be subscribed. Example: [ "1", "28" ]
sendWelcomeEmail	Bool	Defaults to true. If true, the welcome emails will be sent if the lists have one.
trigger	Bool	Defaults to true. If you want to trigger or not the automation or follow-up when subscribing the user.

422: Unprocessable Entity A required parameter is missing

{
    "message": "Emails not provided in the request body."
}

{
    "message": "List IDs not provided in the request body."
}

200: OK Subscription worked

{
    "message": "Users subscribed."
}

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.

{
    "message": "Could not find some users.",
    "errors": [
        "[e-mail]"
    ]
}

Unsubscribe users from lists

POST 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*	String	The API key of a valid AcyMailing license used in the AcyMailing configuration page, tab "License".
Content-Type*	String	application/json

Request Body

Name	Type	Description
emails[]*	Array	The email addresses of users to unsubscribe from the lists. These must match already existing AcyMailing users. Example: [ "[e-mail]", "[e-mail]" ]
listIds[]*	Array	The IDs of the lists from which the users should be unsubscribed. Example: [ "1", "28" ]
sendUnsubscribeEmail	Bool	Defaults to true. If true, the unsubscribe emails will be sent if the lists have one.
trigger	Bool	Defaults to true. If you want to trigger or not the automation or follow-up when subscribing the user.

200: OK Unsubscribe worked

{
    "message": "Users unsubscribed."
}

404: Not Found Some addresses did not match an existing user.

{
    "message": "Could not find some users.",
    "errors": [
        "[e-mail]"
    ]
}

422: Unprocessable Entity A required parameter is missing

{
    "message": "Emails not provided in the request body."
}

{
    "message": "List IDs not provided in the request body."
}