Campaigns

On this page:

Get all campaigns

The /api/campaigns endpoint lists all your campaigns.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/campaigns \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Searching for a specific campaign by its name is possible on this endpoint using ?filter[search]=searchterm. Replace searchterm with the name of your campaign, e.g. ?filter[search]=blackfriday, for searching a campaign list called “Black Friday”.

Filtering is possible on the status of the campaigns using ?filter[status]=sent. Possible values are sent, scheduled, and draft.

Sorting is possible on this endpoint. For example ?sort=-name to sort descending on name.
Allowed sorts:

  • name
  • unique_open_count
  • unique_click_count
  • unsubscribe_rate
  • sent_to_number_of_subscribers
  • sent

Allowed filters:

  • ?filter[search]=
  • ?filter[status]=
  • ?filter[email_list_id]=
  • ?filter[emailList.uuid]=
  • ?filter[contentItem.template.uuid]=

As a result, you get the details of all your campaigns:

{
    "data": [
        {
            "name": null,
            "uuid": "11ce123b-57c4-429b-9840-c79f8047d8aa",
            "email_list_uuid": "845b334b-90de-455d-8e9f-50598d75c06b",
            "from_email": "joh@doe.com",
            "from_name": "John Doe",
            "status": "draft",
            "html": "<html>...</html>\n",
            "structured_html": null,
            "email_html": null,
            "webview_html": null,
            "mailable_class": null,
            "sent_to_number_of_subscribers": "0",
            "segment_class": null,
            "segment_description": "0",
            "open_count": "0",
            "unique_open_count": "0",
            "open_rate": 0,
            "click_count": "0",
            "unique_click_count": "0",
            "click_rate": 0,
            "unsubscribe_count": "0",
            "unsubscribe_rate": "0",
            "bounce_count": "0",
            "bounce_rate": "0",
            "sent_at": null,
            "statistics_calculated_at": null,
            "scheduled_at": null,
            "last_modified_at": "2020-08-06T12:48:41.000000Z",
            "summary_mail_sent_at": null,
            "created_at": "2020-08-06T12:48:41.000000Z",
            "updated_at": "2020-08-06T12:48:41.000000Z"
        },
        ...
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/campaigns?page=1",
        "last": "https://<your-mailcoach-domain>/api/campaigns?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/campaigns",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific campaign

If you don’t want to retrieve all campaigns, you can get a specific campaign if you know its UUID. The example below will get the details of the campaign with UUID “0762df4d-8516-4eb3-95db-b26492cf221c”.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "name": null,
        "uuid": "11ce123b-57c4-429b-9840-c79f8047d8aa",
        "email_list_uuid": "845b334b-90de-455d-8e9f-50598d75c06b",
        "from_email": "joh@doe.com",
        "from_name": "John Doe",
        "status": "draft",
        "html": "<html>...</html>\n",
        "structured_html": null,
        "email_html": null,
        "webview_html": null,
        "mailable_class": null,
        "sent_to_number_of_subscribers": "0",
        "segment_class": null,
        "segment_description": "0",
        "open_count": "0",
        "unique_open_count": "0",
        "open_rate": 0,
        "click_count": "0",
        "unique_click_count": "0",
        "click_rate": 0,
        "unsubscribe_count": "0",
        "unsubscribe_rate": "0",
        "bounce_count": "0",
        "bounce_rate": "0",
        "sent_at": null,
        "statistics_calculated_at": null,
        "scheduled_at": null,
        "last_modified_at": "2020-08-06T12:48:41.000000Z",
        "summary_mail_sent_at": null,
        "created_at": "2020-08-06T12:48:41.000000Z",
        "updated_at": "2020-08-06T12:48:41.000000Z"
    }
}

Add a campaign

To add a campaign, create a POST call to the /api/campaigns/ endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/campaigns \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Campaign name", "email_list_uuid": "845b334b-90de-455d-8e9f-50598d75c06b", "html": "<html>...</html>"}'

Your request payload should also be a valid JSON. The actual payload, when formatted, looks like this:

{
  "name": "Campaign name",
  "email_list_uuid": "0762df4d-8516-4eb3-95db-b26492cf221c",
  "html": "html"
}

The only required fields are the campaign name and email_list_uuid. If you want to pass Markdown when creating a campaign, adding a template_uuid is required.

Fields:

  • name => required | string
  • email_list_uuid => required | string
  • template_uuid => nullable | string
  • segment_uuid => string
  • html => string
  • mailable_class => string
  • schedule_at => date_format:Y-m-d H:i:s
  • utm_tags => boolean
  • add_subscriber_tags => boolean
  • add_subscriber_link_tags => boolean
  • disable_webview => boolean

If the API call succeeds, you will be given output like this:

{
    "data": {
        "uuid": "0762df4d-8516-4eb3-95db-b26492cf221c",
        "name": "Campaign name",
        "html": "<html>...</html>\n",
        ...
    }
}

Using a template

Optionally, you can also pass a template_uuid. You can pass the values of the fields in the template in the fields property. Here is an example of when your template has a title and content field.

Fields in your request:

  • template_uuid: the UUID of your template
  • fields: an array with these keys:
    • title: the value that should be used to fill the title field of your template
    • content: the value that should be used to fill the content field of your template

Using Markdown

If you have configured Mailcoach to use a Markdown field, the content field may contain Markdown and passing a template_uuid is required. We will convert it to HTML.

Laravel example

Here is an example call for when using Laravel:

use Illuminate\Support\Facades\Http;

Http::withToken($yourMailcoachApiToken)
    ->acceptJson()
    ->post('https://<your-mailcoach-domain>/api/campaigns', [
        'name' => 'Name of your campaign',
        'fields' => [
            'title' => 'Value that will fill the title field of the template',
            'content' => 'This value will fill the content field. Can be markdown',
        ],
        'from_email' => 'johndoe@example.com',
        'from_name' => 'John Doe',
        'subject' => "This will be used as the subject of the outgoing mails",
        'email_list_uuid' => '590f564a-3f79-4981-8814-188fe39cc918', // a valid email list uuid
        'template_uuid' => '86232043-4924-40a1-a0c6-6c9568c4e540', // a valid template uuid
    ]);

Update a campaign

To update a campaign, create a PUT call to the /api/campaigns/<uuid> endpoint. In the example below, we are updating the campaign with UUID “0762df4d-8516-4eb3-95db-b26492cf221c”.

$ MAILCOACH_TOKEN="your API token"
$ curl -X PUT https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Updated name", "html":"<html>...</html>"}'

The only required fields are the campaign name and list_id. Other fields are the same when creating a campaign.

If the API call succeeds, you will be given output like this:

{
    "data": {
        "id": 99,
        "name": "Updated name",
        "html": "<html>...</html>\n",
        ...
    }
}

Scheduling a campaign

Scheduling a campaign can be done in the create or update endpoints by specifying a schedule_at parameter with the date in Y-m-d H:i:s format.

$ MAILCOACH_TOKEN="your API token"
$ curl -X PUT https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"schedule_at":"2022-01-01 10:00:00", ...}'

Delete a campaign

To delete a campaign, create a DELETE call to the /api/campaigns/<uuid> endpoint. In the example below, we are deleting the campaign with UUID “0762df4d-8516-4eb3-95db-b26492cf221c”.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeds, you will be given an empty response with a 204 status code.

Sending a test

To send a campaign test, create a POST call to the /api/campaigns/<uuid>/send-test endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/send-test \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@doe.com"}'

The only field is a required email field, which can be a , delimited field with a maximum of 10 email addresses.

If the API call succeeds, you will be given an empty response with a 204 status code.

Sending a campaign

To send a campaign, create a POST call to the /api/campaigns/<uuid>/send endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/send \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

This endpoint doesn’t require a body.

If the API call succeeds, you will be given an empty response with a 204 status code.

Getting a sent campaign’s opens

To get the opens of a campaign, create a GET call to the /api/campaigns/<uuid>/opens endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/opens \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

You can sort on email, open_count, and first_opened_at.
Searching by email can be done by using ?filter[search]=john@doe.com.

If the API call succeeds, you will get output like this:

{
    "data": [
        {
            "subscriber_id": 2,
            "subscriber_email": "john@doe.com",
            "open_count": 1,
            "first_opened_at": "2020-08-06T13:02:46.000000Z"
        }
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/opens?page=1",
        "last": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/opens?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/opens",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Getting a sent campaign’s clicks

To get the clicks of a campaign, create a GET call to the /api/campaigns/<uuid>/clicks endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/clicks \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

You can sort on unique_click_count and click_count.
Searching by url can be done by using ?filter[search]=example.com.

If the API call succeeds, you will get output like this:

{
    "data": [
        {
            "url": "https//example.app",
            "unique_click_count": 1,
            "click_count": 2
        }
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/clicks?page=1",
        "last": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/clicks?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/clicks",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Getting a sent campaign’s unsubscribes

To get the unsubscribes of a campaign, create a GET call to the /api/campaigns/<uuid>/unsubscribes endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

You can sort on created_at.
Searching by email, first_name, or last_name can be done by using ?filter[search]=john.

If the API call succeeds, you will get output like this:

{
    "data": [
        {
            "campaign_id": 1,
            "subscriber_id": 1,
            "subscriber_email": "john@doe.com"
        }
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes?page=1",
        "last": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Getting a send campaign’s subscribers that are bounced

To get the bounced subscribers of a campaign, create a GET call to the /api/campaigns/<uuid>/bounces endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/bounces \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

You can filter on type by using ?filter[type]=bounce.
Possible values are bounce, soft_bounce, and complaint.

You can sort on created_at or email.
Searching by email, first_name, or last_name can be done by using ?filter[search]=john.

If the API call succeeds, you will get output like this:

{
  "data": [
    {
      "subscriber_uuid": "0104156-ddea-373e-bf5c-771f3593a9e1",
      "subscriber_email": "alena64@yahoo.com",
      "subscriber_email_list_uuid": "ee815dfd-806c-36f7-b511-3be143645f59",
      "type": "bounce",
      "bounce_count": 1
    }
  ],
  "links": {
    "first": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/bounces?page=1",
    "last": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/bounces?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://<your-mailcoach-domain>/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/bounces",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}

Error handling

If an error occurs, you will be given a non-HTTP/200 response code. The resulting payload might look like this:

{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}
Subscribers
Tags & Segments