# Campaigns

## Get campaigns

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

Get a collection of campaigns

#### Query Parameters

| Name       | Type  | Description                                                                                           |
| ---------- | ----- | ----------------------------------------------------------------------------------------------------- |
| offset     | Int   | From which element in the database you would like to start getting campaign, by default it's set to 0 |
| limit      | Int   | The number of campaigns you would like to get in your request, by default it's set to 100             |
| filters\[] | Array | Filter with any column in the campaign table and the columns name and subject of the mail table       |

#### 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 An array of campaigns" %}

{% endtab %}

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

{% endtab %}
{% endtabs %}

## Get one Campaign

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

Get a campaign by id

#### Query Parameters

| Name                                         | Type | Description                   |
| -------------------------------------------- | ---- | ----------------------------- |
| campaignId<mark style="color:red;">\*</mark> | Int  | The ID of the campaign to get |

#### 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 campaign with the mail information" %}

{% endtab %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity The ID of the campaign is missing from the request" %}

{% endtab %}
{% endtabs %}

## Create or update a campaign

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

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

{% tabs %}
{% tab title="200: OK Campaign successfully updated" %}

{% endtab %}

{% tab title="201: Created Campaign successfully created" %}

{% endtab %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity Error in the campaign data provided" %}

{% endtab %}
{% endtabs %}

Example of JSON body:

1. If you want to create a simple campaign which will be sent when you call the send endpoint:

{% code fullWidth="true" %}

```json
{
    "subject": "This is a test from the api",// Required
    "name": "Name of the campaign from the api", // Required
    "body": "This is the body of the email", // Not required
    "from_name": "Sender name", // Not required
    "from_email": "sender@email.com", // Not required
    "reply_to_name": "No reply", // Not required
    "reply_to_email": "no-reply@email.com", // Not required
    "bounce_email": "bounce@email.com", // Not required
    "bcc": "address@example.com", // Not required
    "sending_type": "now", // Default "now"
    "listIds": [1, 34, 11] // Not required
}
```

{% endcode %}

2. If you want to create a campaign and schedule it for later:

{% code fullWidth="true" %}

```json
{
    "subject": "This is a test from the api",// Required
    "name": "Name of the campaign from the api", // Required
    "body": "This is the body of the email", // Not required
    "from_name": "Sender name", // Not required
    "from_email": "sender@email.com", // Not required
    "reply_to_name": "No reply", // Not required
    "reply_to_email": "no-reply@email.com", // Not required
    "bounce_email": "bounce@email.com", // Not required
    "bcc": "address@example.com", // Not required
    "sending_type": "scheduled", // Default "now"
    "sending_date": "2024-06-14",
    "listIds": [11] // Not required
}
```

{% endcode %}

3. If you want to create an automatic campaign which will be trigger every cron:

{% code fullWidth="true" %}

```json
{
    "subject": "This is a test from the api",// Required
    "name": "Name of the campaign from the api", // Required
    "body": "This is the body of the email", // Not required
    "from_name": "Sender name", // Not required
    "from_email": "sender@email.com", // Not required
    "reply_to_name": "No reply", // Not required
    "reply_to_email": "no-reply@email.com", // Not required
    "bounce_email": "bounce@email.com", // Not required
    "bcc": "address@example.com", // Not required
    "sending_type": "auto", // Default is "now"
    "frequency": "cron", // Required if sending_type is auto, must be "every" or "cron"
    "need_confirm": 0, // Default is 1
    "start_date": "2024-05-22", // Not required
    "listIds": [1, 34, 11] // Not required
}
```

{% endcode %}

4. If you want to create an automatic campaign that will trigger every X hour, day, week or month:

{% code fullWidth="true" %}

```json
{
    "subject": "This is a test from the api",// Required
    "name": "Name of the campaign from the api", // Required
    "body": "This is the body of the email", // Not required
    "from_name": "Sender name", // Not required
    "from_email": "sender@email.com", // Not required
    "reply_to_name": "No reply", // Not required
    "reply_to_email": "no-reply@email.com", // Not required
    "bounce_email": "bounce@email.com", // Not required
    "bcc": "address@example.com", // Not required
    "sending_type": "auto", // Default is "now"
    "frequency": "every", // Required if sending_type is set to "auto", must be "every" or "cron"
    "frequency_options": { // Required if frequency is set to "every"
        "unit": "month", // Must be "hour", "day", "week" or "month"
        "value": 12
    },
    "need_confirm": 0, // Default is 1
    "start_date": "2024-05-22", // Not required
    "listIds": [1, 34, 11] // Not required
}
```

{% endcode %}

5\. If you want to update a campaign you need to add the campaignId in the body:

{% code fullWidth="true" %}

```json
{
    "campaignId": 12,
    "subject": "This is a test from the api",// Required
    "name": "Name of the campaign from the api", // Required
    "body": "This is the body of the email", // Not required
    "from_name": "Sender name", // Not required
    "from_email": "sender@email.com", // Not required
    "reply_to_name": "No reply", // Not required
    "reply_to_email": "no-reply@email.com", // Not required
    "bounce_email": "bounce@email.com", // Not required
    "bcc": "address@example.com", // Not required
    "sending_type": "now", // Default "now"
    "listIds": [1, 34, 11] // Not required
}
```

{% endcode %}

{% hint style="info" %}
You can only create automatic campaign with 2 type of triggers with the API: On every cron or every X hour, day, week or month.
{% endhint %}

## Send a campaign

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

Send a campaign by ID

#### Query Parameters

| Name                                         | Type   | Description                         |
| -------------------------------------------- | ------ | ----------------------------------- |
| campaignId<mark style="color:red;">\*</mark> | String | ID of the campaign you want to send |

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

{% tabs %}
{% tab title="200: OK Campaign successfully sent" %}

{% endtab %}

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

{% endtab %}

{% tab title="422: Unprocessable Entity The ID of the campaign is missing from the request" %}

{% endtab %}

{% tab title="500: Internal Server Error Database error with detail" %}

{% endtab %}
{% endtabs %}

## Delete a campaign

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

Delete a campaign by ID

#### Query Parameters

| Name                                         | Type | Description                      |
| -------------------------------------------- | ---- | -------------------------------- |
| campaignId<mark style="color:red;">\*</mark> | Int  | The ID of the campaign 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 Campaign deleted" %}

{% endtab %}

{% tab title="422: Unprocessable Entity The ID of the campaign is missing from the request" %}

{% endtab %}

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

{% endtab %}

{% tab title="500: Internal Server Error Database error with detail" %}

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