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