Automation mails

On this page:

Automation mails are the reusable emails that automations send. They are managed independently of the automations that use them, the same way you manage them under the “Emails” section in the Mailcoach UI.

Get all automation mails

The /api/automation-mails endpoint lists all your automation mails.

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

Searching for a specific automation mail by its name or subject is possible using ?filter[search]=searchterm, e.g. ?filter[search]=welcome.

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

  • name
  • created_at

Allowed filters:

  • ?filter[search]=
  • ?filter[name]=
  • ?filter[uuid]=

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

{
    "data": [
        {
            "uuid": "11ce123b-57c4-429b-9840-c79f8047d8aa",
            "name": "Welcome email",
            "template_uuid": null,
            "from_email": "john@doe.com",
            "subject": "Welcome aboard",
            "html": "<html>...</html>\n",
            "structured_html": null,
            "email_html": null,
            "webview_html": null,
            "fields": [],
            "mailable_class": null,
            "utm_tags": true,
            "add_subscriber_tags": false,
            "add_subscriber_link_tags": false,
            "sent_to_number_of_subscribers": 0,
            "open_count": 0,
            "unique_open_count": 0,
            "open_rate": 0,
            "click_count": 0,
            "unique_click_count": 0,
            "click_rate": 0,
            "created_at": "2026-03-15T12:48:41.000000Z",
            "updated_at": "2026-03-15T12:48:41.000000Z"
        },
        ...
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/automation-mails?page=1",
        "last": "https://<your-mailcoach-domain>/api/automation-mails?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/automation-mails",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific automation mail

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

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

Response:

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

Add an automation mail

To add an automation mail, create a POST call to the /api/automation-mails endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/automation-mails \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Welcome email", "subject": "Welcome aboard", "html": "<html>...</html>"}'

The only required field is the name. When you don’t pass a subject, the name is used as the subject. If you want to pass Markdown when creating an automation mail, adding a template_uuid is required.

Fields:

  • name => required | string
  • subject => nullable | string
  • template_uuid => nullable | string
  • html => nullable | string
  • fields => nullable | array
  • utm_tags => nullable | boolean
  • add_subscriber_tags => nullable | boolean
  • add_subscriber_link_tags => nullable | boolean

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

{
    "data": {
        "uuid": "0762df4d-8516-4eb3-95db-b26492cf221c",
        "name": "Welcome email",
        "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

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/automation-mails', [
        'name' => 'Welcome email',
        'subject' => 'Welcome aboard',
        'template_uuid' => '86232043-4924-40a1-a0c6-6c9568c4e540', // a valid template uuid
        'fields' => [
            'title' => 'Value that will fill the title field of the template',
            'content' => 'This value will fill the content field. Can be markdown',
        ],
    ]);

Update an automation mail

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

$ MAILCOACH_TOKEN="your API token"
$ curl -X PUT https://<your-mailcoach-domain>/api/automation-mails/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 field is the name. The other fields are the same as when creating an automation mail.

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

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

Delete an automation mail

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

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://<your-mailcoach-domain>/api/automation-mails/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.

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."
        ]
    }
}
Sends
Transactional emails