Campaigns
On this page:
- Get all campaigns
- Get a specific campaign
- Add a campaign
- 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
- Getting a send campaign’s subscribers that are bounced
- Error handling
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.