Campaigns | Docs | Mailcoach

Get all campaigns

The /api/campaigns endpoint lists all your campaigns.

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

Searching is possible on this endpoint using ?filter[search]=searchterm for searching.

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

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-domain]].mailcoach.app/api/campaigns?page=1",
        "last": "https://[[your-domain]].mailcoach.app/api/campaigns?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://[[your-domain]].mailcoach.app/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 ID. The example below will get the details of campaign ID 99.

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-domain]].mailcoach.app/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-domain]].mailcoach.app/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 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's name and email_list_uuid.

Fields:

name => required | string
email_list_uuid => required | string
segment_uuid => string
html => string
mailable_class => string
schedule_at => date_format:Y-m-d H:i:s

If the API call succeeded, you'll 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's an example for 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 have configured Mailcoach to use a Markdown field, then the content field may contain Markdown. We'll convert it to HTML.

Laravel example

Here's an example call for when you use Laravel:

use Illuminate\Support\Facades\Http;

Http::withToken($yourMailcoachApiToken)
    ->acceptJson()
    ->post('https://[[your-domain]].mailcoach.app/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're updating the campaign with ID 99.

$ MAILCOACH_TOKEN="your API token"
$ curl -X PUT https://[[your-domain]].mailcoach.app/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's name and list_id. Other fields are the same when creating a campaign.

If the API call succeeded, you'll 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-domain]].mailcoach.app/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're deleting the campaign with ID 99.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://[[your-domain]].mailcoach.app/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 succeeded, you'll 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-domain]].mailcoach.app/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 succeeded, you'll 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-domain]].mailcoach.app/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 succeeded, you'll 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-domain]].mailcoach.app/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 succeeded, you'll 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-domain]].mailcoach.app/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/opens?page=1",
        "last": "https://[[your-domain]].mailcoach.app/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-domain]].mailcoach.app/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-domain]].mailcoach.app/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 succeeded, you'll get output like this

{
    "data": [
        {
            "url": "https//example.app",
            "unique_click_count": 1,
            "click_count": 2
        }
    ],
    "links": {
        "first": "https://[[your-domain]].mailcoach.app/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/clicks?page=1",
        "last": "https://[[your-domain]].mailcoach.app/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-domain]].mailcoach.app/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-domain]].mailcoach.app/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 succeeded, you'll get output like this

{
    "data": [
        {
            "campaign_id": 1,
            "subscriber_id": 1,
            "subscriber_email": "john@doe.com"
        }
    ],
    "links": {
        "first": "https://[[your-domain]].mailcoach.app/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes?page=1",
        "last": "https://[[your-domain]].mailcoach.app/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-domain]].mailcoach.app/api/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Error handling

If an error occurred, you'll 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."
        ]
    }
}

Get all campaigns#

Get a specific campaign#

Add a campaign#

Using a template#

Using Markdown#

Laravel example#

Update a campaign#

Scheduling a campaign#

Delete a campaign#

Sending a test#

Sending a campaign#

Getting a sent campaign's opens#

Getting a sent campaign's clicks#

Getting a sent campaign's unsubscribes#

Error handling#

Get all campaigns

Get a specific campaign

Add a campaign

Using a template

Using Markdown

Laravel example

Update a campaign

Scheduling a campaign

Delete a campaign

Sending a test

Sending a campaign

Getting a sent campaign's opens

Getting a sent campaign's clicks

Getting a sent campaign's unsubscribes

Error handling