Emails

Use this endpoint to manipulate and obtain details on Mautic’s Emails.

Using Mautic’s API Library

You can interact with this API through the Mautic API Library as follows, or use the various http endpoints as described in this document.

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://example.com";
$api      = new MauticApi();
$emailApi = $api->newApi("emails", $auth, $apiUrl);

Get Email

<?php

//...
$email = $emailApi->get($id);

Get an individual Email by ID.

HTTP Request

GET /emails/ID

Response

Expected Response Code: 200

{
    "email": {
        "isPublished": true,
        "dateAdded": "2017-02-03T16:51:06+00:00",
        "dateModified": "2017-02-03T19:11:54+00:00",
        "createdBy": 1,
        "createdByUser": "John Doe",
        "modifiedBy": 1,
        "modifiedByUser": "John Doe",
        "id": 1,
        "name": "API Test Email",
        "subject": "Email created via API",
        "fromAddress": "test@example.com",
        "fromName": "Test From Name",
        "replyToAddress": "reply@example.com",
        "bccAddress": "bcc@example.com",
        "useOwnerAsMailer": false,
        "template": "blank",
        "content": [],
        "utmTags": [],
        "plainText": "Plain text content here",
        "customHtml": "<h1>Custom HTML content</h1>",
        "emailType": "list",
        "translationChildren": [],
        "translationParent": null,
        "variantChildren": [],
        "variantParent": null,
        "variantSettings": [],
        "variantStartDate": null,
        "publishUp": null,
        "publishDown": null,
        "readCount": 0,
        "sentCount": 0,
        "revision": 1,
        "category": null,
        "lists": [
            {
                "createdByUser": "John Doe",
                "modifiedByUser": "John Doe",
                "id": 2,
                "name": "Test Segment",
                "alias": "test-segment",
                "description": "Description for test segment"
            }
        ],
        "language": "en",
        "publicPreview": false,
        "assetAttachments": [],
        "unsubscribeForm": null,
        "preferenceCenter": null,
        "dynamicContent": [],
        "variantSentCount": 0,
        "variantReadCount": 0,
        "headers": []
    }
}

Email Properties

Name	Type	Description
`id`	int	ID of the Email
`name`	string	Name of the Email
`subject`	string	Subject of the Email
`fromAddress`	string	From email address
`fromName`	string	From name
`replyToAddress`	string	Reply-to email address
`bccAddress`	string	BCC email address
`useOwnerAsMailer`	boolean	Whether to use the Contact owner as the mailer
`template`	string	Template used for the Email
`content`	array	Array of content for the template
`utmTags`	array	Array of UTM tags for tracking
`plainText`	string	Plain text version of the Email
`customHtml`	string	Custom HTML content of the Email
`emailType`	string	Type of the Email - `list` or `template`
`publishUp`	datetime/null	Date/time when the Email should be published
`publishDown`	datetime/null	Date/time when the Email should be unpublished
`readCount`	int	Number of times the Email was read
`sentCount`	int	Number of times the Email was sent
`revision`	int	Revision number of the Email
`category`	object/null	Category the Email belongs to
`lists`	array	Array of Segments/Lists the Email is assigned to
`language`	string	Language of the Email
`publicPreview`	boolean	Whether the Email has public preview enabled
`assetAttachments`	array	Array of assets attached to the Email
`unsubscribeForm`	object/null	Unsubscribe form associated with the Email
`preferenceCenter`	object/null	Preference center page associated with the Email
`dynamicContent`	array	Array of dynamic content variants
`variantSentCount`	int	Number of times Email variants were sent
`variantReadCount`	int	Number of times Email variants were read
`headers`	array	Array of custom headers
`isPublished`	boolean	Published state
`dateAdded`	datetime	Date/time Email was created
`createdBy`	int	ID of the User that created the Email
`createdByUser`	string	Name of the User that created the Email
`dateModified`	datetime/null	Date/time Email was last modified
`modifiedBy`	int	ID of the User that last modified the Email
`modifiedByUser`	string	Name of the User that last modified the Email

List Emails

<?php

//...
$emails = $emailApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

Returns a list of contact Emails available to the User. This list is filterable and sortable.

HTTP Request

GET /emails

Query Parameters

Name	Description
`search`	String or search command to filter entities by.
`start`	Starting row for the entities returned. Defaults to 0.
`limit`	Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
`orderBy`	Column to sort by. Can use any column listed in the response. However, you need to change all properties in the response written in `camelCase` a bit. Before every capital, add an underscore `_` and then change the capital letters to non-capital letters. So `dateAdded` becomes `date_added`, `modifiedBy` becomes `modified_by`, etc.
`orderByDir`	Sort direction: `asc` or `desc`.
`publishedOnly`	Only return currently published entities.
`minimal`	Return only array of entities without additional lists in it.

Response

Expected Response Code: 200

{
    "total": 1,
    "emails": {
        "1": {
            "isPublished": true,
            "dateAdded": "2017-02-03T16:51:06+00:00",
            "dateModified": "2017-02-03T19:11:54+00:00",
            "createdBy": 1,
            "createdByUser": "John Doe",
            "modifiedBy": 1,
            "modifiedByUser": "John Doe",
            "id": 1,
            "name": "API Test Email",
            "subject": "Email created via API",
            "fromAddress": "test@example.com",
            "fromName": "Test From Name",
            "replyToAddress": "reply@example.com",
            "bccAddress": "bcc@example.com",
            "useOwnerAsMailer": false,
            "template": "blank",
            "content": [],
            "utmTags": [],
            "plainText": "Plain text content here",
            "customHtml": "<h1>Custom HTML content</h1>",
            "emailType": "list",
            "publishUp": null,
            "publishDown": null,
            "readCount": 0,
            "sentCount": 0,
            "revision": 1,
            "category": null,
            "lists": [
                {
                    "id": 2,
                    "name": "Test Segment",
                    "alias": "test-segment",
                    "description": "Description for test segment"
                }
            ],
            "language": "en",
            "publicPreview": false,
            "assetAttachments": [],
            "unsubscribeForm": null,
            "preferenceCenter": null,
            "dynamicContent": [],
            "variantSentCount": 0,
            "variantReadCount": 0,
            "headers": []
        }
    }
}

Properties

Same as Get Email.

Create Email

<?php

$data = array(
    'name'       => 'Email created via API',
    'subject'    => 'Hello World!',
    'emailType'  => 'list',
    'customHtml' => '<h1>Hello from API!</h1>',
    'lists'      => array(1, 2),
);

$email = $emailApi->create($data);

Create a new Email.

HTTP Request

POST /emails/new

POST Parameters

Name	Type	Description
`name`	string	Email name is the only required field
`subject`	string	Email subject
`fromAddress`	string	From email address
`fromName`	string	From name
`replyToAddress`	string	Reply-to email address
`bccAddress`	string	BCC email address
`useOwnerAsMailer`	boolean	Whether to use the Contact owner as the mailer
`template`	string	Template to use for the Email
`content`	array	Array of content for the template
`utmTags`	array	Array of UTM tags for tracking
`plainText`	string	Plain text version of the Email
`customHtml`	string	Custom HTML content of the Email
`emailType`	string	Type of the Email - `list` or `template`
`publishUp`	datetime	Date/time when the Email should be published
`publishDown`	datetime	Date/time when the Email should be unpublished
`category`	int	ID of the category to assign the Email to
`lists`	array	Array of Segment/List IDs to assign the Email to
`language`	string	Language of the Email
`publicPreview`	boolean	Whether to enable public preview for the Email
`assetAttachments`	array	Array of asset IDs to attach to the Email
`unsubscribeForm`	int	ID of the unsubscribe form to use
`preferenceCenter`	int	ID of the preference center page to use
`dynamicContent`	array	Array of dynamic content variants
`headers`	array	Array of custom headers
`isPublished`	boolean	Published state

Response

Expected Response Code: 201

Properties

Same as Get Email.

Edit Email

<?php

$id   = 1;
$data = array(
    'name'    => 'New email name',
    'subject' => 'New subject line',
);

// Create new a Email of ID 1 isn't found?
$createIfNotFound = true;

$email = $emailApi->edit($id, $data, $createIfNotFound);

Edit an existing Email. Note that this supports PUT or PATCH depending on the desired behavior.

PUT creates an Email if the given ID doesn’t exist and clears all the Email information, adds the information from the request. PATCH fails if the Email with the given ID doesn’t exist and updates the Email field values with the values from the request.

HTTP Request

To edit an Email and return a 404 if the Email isn’t found:

PATCH /emails/ID/edit

To edit an Email and create a new one if the Email isn’t found:

PUT /emails/ID/edit

POST Parameters

Name	Type	Description
`name`	string	Email name
`subject`	string	Email subject
`fromAddress`	string	From email address
`fromName`	string	From name
`replyToAddress`	string	Reply-to email address
`bccAddress`	string	BCC email address
`useOwnerAsMailer`	boolean	Whether to use the Contact owner as the mailer
`template`	string	Template to use for the Email
`content`	array	Array of content for the template
`utmTags`	array	Array of UTM tags for tracking
`plainText`	string	Plain text version of the Email
`customHtml`	string	Custom HTML content of the Email
`emailType`	string	Type of the Email - `list` or `template`
`publishUp`	datetime	Date/time when the Email should be published
`publishDown`	datetime	Date/time when the Email should be unpublished
`category`	int	ID of the category to assign the Email to
`lists`	array	Array of Segment/List IDs to assign the Email to
`language`	string	Language of the Email
`publicPreview`	boolean	Whether to enable public preview for the Email
`assetAttachments`	array	Array of asset IDs to attach to the Email
`unsubscribeForm`	int	ID of the unsubscribe form to use
`preferenceCenter`	int	ID of the preference center page to use
`dynamicContent`	array	Array of dynamic content variants
`headers`	array	Array of custom headers
`isPublished`	boolean	Published state

Response

If PUT, the expected response code is 200 if the Email was edited or 201 if created. If PATCH, the expected response code is 200.

Properties

Same as Get Email.

Delete Email

<?php

$email = $emailApi->delete($id);

Delete an Email.

HTTP Request

DELETE /emails/ID/delete

Response

Expected Response Code: 200

Properties

Same as Get Email.

Create Batch Emails

<?php

$data = array(
    array(
        'name'       => 'Email A created via API',
        'subject'    => 'Hello from Email A!',
        'emailType'  => 'list',
        'customHtml' => '<h1>Hello from Email A!</h1>',
        'lists'      => array(1),
    ),
    array(
        'name'       => 'Email B created via API',
        'subject'    => 'Hello from Email B!',
        'emailType'  => 'list',
        'customHtml' => '<h1>Hello from Email B!</h1>',
        'lists'      => array(2),
    )
);

$emails = $emailApi->createBatch($data);

Create a batch of new Emails.

HTTP Request

POST /emails/batch/new

POST Parameters

Array of Email data objects. Each object should contain the same parameters as for creating a single Email.

Response

Expected Response Code: 201

Properties

Array of Emails. Each record is the same as Get Email.

Edit Batch Emails

<?php

$data = array(
    array(
        'id'      => 1,
        'name'    => 'Updated Email A name',
        'subject' => 'Updated Email A subject',
    ),
    array(
        'id'      => 2,
        'name'    => 'Updated Email B name',
        'subject' => 'Updated Email B subject',
    )
);

$emails = $emailApi->editBatch($data);

Edit multiple Emails in one request. Note that this supports PUT or PATCH depending on the desired behavior.

PUT creates an Email if the given ID doesn’t exist and clears all the Email information, adds the information from the request. PATCH fails if the Email with the given ID doesn’t exist and updates the Email field values with the values from the request.

HTTP Request

To edit Emails and return a 404 if an Email isn’t found:

PATCH /emails/batch/edit

To edit Emails and create new ones if an Email isn’t found:

PUT /emails/batch/edit

POST Parameters

Array of Email data objects. Each object should contain an id field and the fields to be updated.

Response

If PUT, the expected response code is 200 if Emails were edited or 201 if created. If PATCH, the expected response code is 200.

Properties

Array of Emails. Each record is the same as Get Email.

Delete Batch Emails

<?php

$emails = $emailApi->deleteBatch($ids);

Delete multiple Emails.

HTTP Request

DELETE /emails/batch/delete

If you aren’t using PHP, here is a URL example:

DELETE https://[example.com]/api/emails/batch/delete?ids=1,2

Response

Expected Response Code: 200

Properties

Array of Emails. Each record is the same as Get Email.

Send Email to Segment

<?php

// Send to all Contacts in the Email's assigned lists
$response = $emailApi->send($id);

// Send to specific list(s)
$response = $emailApi->sendToLists($id, $listIds);

Send an Email to the Contacts in the Email’s assigned lists or to provided list IDs.

HTTP Request

POST /emails/ID/send

POST Parameters

Name	Description
`lists`	Array of list IDs to send to. If not provided, will use the Email’s assigned lists.
`limit`	Maximum number of Contacts to send to. If not provided, will send to all Contacts.
`batch`	Batch size for sending. If not provided, will send all at once.

Response

Expected Response Code: 200

{
    "success": 1,
    "sentCount": 1,
    "failedRecipients": 0
}

Send Email to Contact

<?php

$response = $emailApi->sendToContact($emailId, $contactId, $options);

Send an Email to a specific Contact.

HTTP Request

POST /emails/ID/contact/CONTACT_ID/send

POST Parameters

Name	Description
`tokens`	Array of tokens to replace in the Email content
`assetAttachments`	Array of asset IDs to attach to the Email

Response

Expected Response Code: 200

{
    "success": true
}

Tokens

You can send custom tokens to the Email via the tokens parameter. Tokens should be in the format {token_name} and can be used in the Email content.

<?php

$tokens = array(
    '{first_name}' => 'John',
    '{last_name}'  => 'Doe',
    '{custom_token}' => 'Custom Value'
);

$response = $emailApi->sendToContact($emailId, $contactId, array('tokens' => $tokens));

Create Email Reply

<?php

$response = $emailApi->reply($trackingHash);

Create a reply to an Email using the tracking hash from the Email statistics.

HTTP Request

POST /emails/reply/TRACKING_HASH

Response

Expected Response Code: 201

{
    "success": true
}