Campaigns

On this page:

Set MAILCOACH_API_URL and MAILCOACH_TOKEN as shown in Authentication. Creating a campaign makes a draft; sending is a separate action. See the generated API reference for complete schemas.

Get all campaigns

curl "$MAILCOACH_API_URL/campaigns" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Results are paginated. Supported filters include filter[search], filter[status], filter[email_list_id], filter[emailList.uuid] and filter[contentItem.template.uuid]. For example, use ?filter[status]=draft to list drafts.

Sort by name, email_list_id, unique_open_count, unique_click_count, unsubscribe_rate, sent_to_number_of_subscribers or sent. Prefix a field with - for descending order, for example ?sort=-name.

Get a specific campaign

Use the campaign UUID returned by the API:

curl "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

The campaign is returned under data, including its uuid, name, subject and content. See the API reference for all fields.

Add a campaign

Both name and email_list_uuid are required. This example creates an HTML draft without sending it:

curl -X POST "$MAILCOACH_API_URL/campaigns" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"November newsletter","email_list_uuid":"a69075c6-ff5c-4b6a-b217-12026cb72e4f","subject":"News from our team","html":"<p>Here is our latest news.</p>"}'

Optional fields include subject, template_uuid, fields, segment_uuid, html, schedule_at, utm_tags, add_subscriber_tags, add_subscriber_link_tags and disable_webview.

The create and update endpoints do not accept sender overrides through from, from_email or from_name. Configure the sender defaults on the email list instead. Returned sender fields are not necessarily writable fields.

The response contains the new campaign under data; save its uuid for later requests.

Using a template

Pass template_uuid and a fields object matching your template’s fields. For a template with title and content fields, a request body could be:

{
    "name": "November newsletter",
    "email_list_uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
    "template_uuid": "86232043-4924-40a1-a0c6-6c9568c4e540",
    "subject": "News from our team",
    "fields": {
        "title": "November news",
        "content": "Here is our latest news."
    }
}

Using Markdown

To use Markdown, select a template configured with a Markdown field, pass its template_uuid, and put Markdown in that field inside fields. Sending Markdown directly as html does not convert it.

Laravel example

Keep the token and endpoint in your application’s configuration. This creates a draft and throws an exception if the API rejects the request:

use Illuminate\Support\Facades\Http;

$campaign = Http::withToken(config('services.mailcoach.token'))
    ->acceptJson()
    ->post(rtrim(config('services.mailcoach.api_url'), '/').'/campaigns', [
        'name' => 'November newsletter',
        'email_list_uuid' => config('services.mailcoach.email_list_uuid'),
        'subject' => 'News from our team',
        'html' => '<p>Here is our latest news.</p>',
    ])
    ->throw()
    ->json('data');

Configure services.mailcoach.api_url with your team’s API URL including /api. See the newsletter walkthrough for configuration and a template-based example.

Update a campaign

Include both name and email_list_uuid when updating, even if only the content changes. The required field is email_list_uuid, not list_id.

curl -X PUT "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Updated newsletter","email_list_uuid":"a69075c6-ff5c-4b6a-b217-12026cb72e4f","html":"<p>Updated news.</p>"}'

The response contains the updated campaign under data.

Scheduling a campaign

Creating or updating with schedule_at schedules delivery. Supply the date in Y-m-d H:i:s format and include both required campaign fields. Choose your intended future date before running this request:

curl -X PUT "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"November newsletter","email_list_uuid":"a69075c6-ff5c-4b6a-b217-12026cb72e4f","schedule_at":"2027-11-20 10:00:00"}'

Delete a campaign

curl -X DELETE "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Success returns an empty 204 response.

Sending a test

This sends an email to the supplied test address, not to the campaign’s audience. The required email field accepts up to ten comma-delimited addresses.

curl -X POST "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/send-test" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"your-address@example.com"}'

Success returns an empty 204 response.

Sending a campaign

Only run this when you are ready to send to the campaign’s audience. No request body is required.

curl -X POST "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/send" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Success returns an empty 204 response. A campaign that cannot be sent can return 400; inspect the error before retrying.

Getting a sent campaign’s opens

curl "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/opens" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Getting a sent campaign’s clicks

curl "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/clicks" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Click statistics have an additional burst limit.

Getting a sent campaign’s unsubscribes

curl "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/unsubscribes" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Getting a send campaign’s subscribers that are bounced

curl "$MAILCOACH_API_URL/campaigns/0762df4d-8516-4eb3-95db-b26492cf221c/bounces" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Statistics responses are paginated. See the API reference for the event fields returned by each endpoint.

Error handling

See common errors and retry guidance. A 204 response is successful and has no JSON body. Do not automatically repeat a send after a timeout: the first request may already have been accepted.