Emails

使用此端点来操作并获取有关 Mautic 的电子邮件的详细信息。

使用 Mautic API 库

您可以使用以下 :xref:`Mautic API 库 与此 API 进行交互，或者使用本文档中描述的各种 HTTP 端点。

<?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);

获取电子邮件

检索单个电子邮件。

<?php

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

HTTP 请求

GET /emails/ID

响应

  • 当请求成功检索到电子邮件时，返回 200 OK。
{
“email”: {

“isPublished”: true, “dateAdded”: “2026-02-19T04:17:46+00:00”, “dateModified”: “2026-02-19T14:49:06+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “Admin Mautic”, “id”: 1, “name”: “Acme General Conference Success”, “subject”: “Acme General Conference Success”, “language”: “en”, “category”: null, “fromAddress”: “john.doe@acme.com”, “fromName”: “John Doe”, “replyToAddress”: null, “bccAddress”: null, “useOwnerAsMailer”: false, “utmTags”: {

“utmSource”: null, “utmMedium”: null, “utmCampaign”: null, “utmContent”: null

}, “preheaderText”: null, “customHtml”: “”, “plainText”: null, “template”: “_make-announcement”, “emailType”: “template”, “publishUp”: null, “publishDown”: null, “publicPreview”: false, “readCount”: 0, “sentCount”: 0, “revision”: 2, “assetAttachments”: [], “variantStartDate”: null, “variantSentCount”: 0, “variantReadCount”: 0, “variantParent”: null, “variantChildren”: [], “translationParent”: null, “translationChildren”: [], “unsubscribeForm”: null, “dynamicContent”: [

{

“tokenName”: “Dynamic Content 1”, “content”: “Default Dynamic Content”, “filters”: [

{

“content”: null, “filters”: []

}

]

}

], “lists”: [], “headers”: [], “grapesjsbuilder”: {

“customMjml”: “<mjml>rn <mj-head>rnt<!– CSS-STYLE –>rnt<mj-style inline="inline"> p, li {margin:0 !important; padding:0; line-height:1.4em;}rnt</mj-style>rn </mj-head>rn <!– BODY –>rn <mj-body background-color="#f4f4f4">rnt<mj-section padding-top="40px" background-color="#ffffff">rnt <mj-column>rntt<mj-text font-size="11px" align="center">rntt <p>rnttt<span data-fr-verified="true"><span data-fr-verified="true" class="atwho-inserted">{webview_text}</span>⁠⁠⁠⁠⁠⁠⁠</span>rntt </p>rntt</mj-text>rntt<mj-spacer>rntt</mj-spacer>rntt<mj-image src="/app/assets/images/placeholder-logo.png?v5214f417" width="70px" padding-bottom="0px" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff">rnt <mj-column width="550px">rntt<mj-text font-size="16px" align="center" font-style="italic" color="#525252">rntt <p>Ok, let’s make an announcementrntt </p>rntt</mj-text>rntt<mj-spacer height="40px">rntt</mj-spacer>rntt<mj-text font-size="24px" align="center" font-weight="700">rntt <p>Start customizing your emailrntt </p>rntt</mj-text>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff" padding-top="0px">rnt <mj-column padding-top="0px">rntt<mj-image src="/app/assets/images/placeholder-image.png?v5214f417" padding-right="0px" padding-left="0px" padding-bottom="0px" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff" padding-top="0px">rnt <mj-column padding-top="0px">rntt<mj-image src="/app/assets/images/placeholder-image.png?v5214f417" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt <mj-column padding-top="0px">rntt<mj-image src="/app/assets/images/placeholder-image.png?v5214f417" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff">rnt <mj-column width="550px">rntt<mj-text font-size="16px" align="center">rntt <p>Make your announcements pop with an eye-catching visual, then provide the crucial details for engagement.rntt </p>rntt <p>⁠⁠⁠⁠⁠⁠⁠rnttt<br/>Customize this section by inserting your own images or choosing a striking solid color backdrop.rntt </p>rntt</mj-text>rntt<mj-spacer height="30px">rntt</mj-spacer>rntt<mj-divider border-width="2px" border-color="#d0d0d0">rntt</mj-divider>rntt<mj-spacer height="30px">rntt</mj-spacer>rntt<mj-text font-size="22px" font-weight="700">rntt <p>Lead with an eye-catching titlerntt </p>rntt</mj-text>rntt<mj-text font-size="16px">rntt <p>Present your news in a brief paragraph. For crucial points, use a bulleted list:rntt </p>rntt <ul>rnttt<li>rnttt <span class="ck-list-bogus-paragraph"><span class="ck-list-bogus-paragraph">What’s on offer</span></span>rnttt</li>rnttt<li>rnttt <span class="ck-list-bogus-paragraph"><span class="ck-list-bogus-paragraph">Where to find us</span></span>rnttt</li>rnttt<li>rnttt <span class="ck-list-bogus-paragraph"><span class="ck-list-bogus-paragraph">Timing specifics</span></span>rnttt</li>rntt </ul>rntt <p>Be concise to motivate readers to explore your website for the full story.rntt </p>rntt</mj-text>rntt<mj-button href="https://" background-color="#000000" inner-padding="16px 32px" border-radius="0px 0px 0px 0px" font-size="16px" align="left">Buttonrntt</mj-button>rntt<mj-spacer align="center">rntt</mj-spacer>rnt </mj-column>rnt</mj-section>rnt<mj-section padding-top="0" padding-bottom="20px" background-color="#000000">rnt <mj-column>rntt<mj-spacer height="40px">rntt</mj-spacer>rntt<mj-image src="/app/assets/images/placeholder-logo-inverse.png?v5214f417" width="70px" padding-bottom="0px">rntt</mj-image>rntt<mj-spacer>rntt</mj-spacer>rntt<mj-text font-family="Ubuntu, Helvetica, Arial, sans-serif" line-height="1.5" align="center" padding-top="0px" padding-bottom="0px" font-size="12px" color="white">rntt <p>Amazing Companyrnttt<br/>11111 Beautiful City, 1212 Nice Streetrnttt<br/>Brazilrnttt<br/>rntt </p>rntt</mj-text>rntt<mj-spacer>rntt</mj-spacer>rntt<mj-text font-size="11px" align="center" color="#a1a1a1">rntt <p>Fancy seeing you down here. You’re getting this email because you gave us your email address.rntt </p>rntt <p>Want to change how you receive these emails?rntt </p>rntt</mj-text>rntt<mj-text font-size="11px" align="center" color="#a1a1a1">rntt <p>rnttt<span data-fr-verified="true"><span data-fr-verified="true" class="atwho-inserted">{unsubscribe_text}</span>⁠⁠⁠⁠⁠⁠⁠</span>rntt </p>rntt</mj-text>rntt<mj-spacer>rntt</mj-spacer>rnt </mj-column>rnt</mj-section>rn </mj-body>rn</mjml>rn”

}

}

}

邮件属性

    • Name

      • Type

      • Description

      • isPublished

      • boolean

      • 邮件发布状态

      • dateAdded

      • datetime

      • 邮件记录创建日期和时间

      • dateModified

      • datetime

      • 邮件记录上次修改日期和时间

      • createdBy

      • integer

      • 创建该邮件的用户的ID

      • createdByUser

      • string

      • 创建该邮件的用户姓名

      • modifiedBy

      • integer

      • 最后修改该邮件的用户的ID

      • modifiedByUser

      • string

      • 最后修改该邮件的用户姓名

      • id

      • integer

      • 邮件的ID

      • name

      • string

      • 邮件名称

      • subject

      • string

      • 邮件主题

      • language

      • string

      • 邮件的语言代码，例如 en、fr 等

      • category

      • object

      • 邮件所属的分类

      • fromAddress

      • string

      • 发件人邮箱地址

      • fromName

      • string

      • 发件人姓名

      • replyToAddress

      • string

      • 回复目标Email地址

      • bccAddress

      • string

      • 抄送目标Email地址

      • useOwnerAsMailer

      • boolean

      • 使用联系人所有者作为发送者的状态 - 设置为 1 或 true 以使用联系人所有者作为发送者

      • utmTags

      • associative array

      • 邮件UTM标签的关联数组

      • preheaderText

      • string

      • 显示在主题行之后的摘要文本

      • customHtml

      • string

      • 邮件的自定义HTML内容

      • plainText

      • string

      • 邮件的纯文本版本

      • template

      • string

      • 用于设置邮件样式的模板

      • emailType

      • string

      • 邮件类型 - list 或 template

      • publishUp

      • datetime

      • 邮件的激活日期和时间

      • publishDown

      • datetime

      • 邮件的停用日期和时间

      • publicPreview

      • boolean

      • 公共预览状态

      • readCount

      • integer

      • 用户阅读邮件的次数

      • sentCount

      • integer

      • 系统发送邮件的次数

      • revision

      • integer

      • 邮件的版本号

      • assetAttachments

      • array

      • 附加到邮件的附件数组

      • variantStartDate

      • datetime

      • A/B测试邮件的激活日期和时间

      • variantSentCount

      • integer

      • 系统发送邮件变体的次数

      • variantReadCount

      • integer

      • 用户阅读邮件变体的次数

      • variantParent

      • integer

      • 邮件变体的父级邮件ID

      • variantChildren

      • array

      • 邮件变体子级的数组

      • translationParent

      • integer

      • 父翻译邮件的ID

      • translationChildren

      • array

      • 翻译父级邮件的邮件ID数组

      • unsubscribeForm

      • object

      • 邮件的退订表单

      • dynamicContent

      • array

      • 动态内容变体的数组

      • lists

      • array

      • 接收该邮件的分组数组

      • headers

      • array

      • 自定义标头的数组

      • grapesjsbuilder

      • associative array

      • 邮件构建器配置的关联数组

列出邮件

获取邮件列表。

<?php
// ...

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

HTTP 请求

GET /emails

查询参数

名称

类型

描述

search

string

用于过滤实体的字符串或搜索命令

start

integer

返回实体的起始行，默认为 0

limit

integer

要返回的最大实体数量，默认为 30

orderBy

string

用于排序的列。响应中的任何列都有效。

注意: 将 camelCase 属性转换为 snake_case。例如，dateAdded 变为 date_added，webhookUrl 变为 webhook_url，依此类推。

orderByDir

string

排序方向，可以是 asc 或 desc

publishedOnly

boolean

仅返回当前已发布的实体

minimal

boolean

仅返回简单的实体映射对象，不包含其他列表

响应

  • 当请求成功获取邮件列表时，返回 200 OK。
{

“total”: 2, “emails”: {

“1”: {

“isPublished”: true, “dateAdded”: “2026-02-19T04:17:46+00:00”, “dateModified”: “2026-02-19T15:14:49+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “Admin Mautic”, “id”: 1, “name”: “Acme General Conference Success”, “subject”: “Acme General Conference Success”, “language”: “en”, “category”: null, “fromAddress”: “john.doe@acme.com”, “fromName”: “John Doe”, “replyToAddress”: null, “bccAddress”: null, “useOwnerAsMailer”: false, “utmTags”: {

“utmSource”: null, “utmMedium”: null, “utmCampaign”: null, “utmContent”: null

}, “preheaderText”: null, “customHtml”: “”, “plainText”: null, “template”: “mautic_code_mode”, “emailType”: “template”, “publishUp”: null, “publishDown”: null, “publicPreview”: false, “readCount”: 0, “sentCount”: 0, “revision”: 4, “assetAttachments”: [], “variantStartDate”: null, “variantSentCount”: 0, “variantReadCount”: 0, “variantParent”: null, “variantChildren”: [], “translationParent”: null, “translationChildren”: [], “unsubscribeForm”: null, “dynamicContent”: [

{

“tokenName”: “Dynamic Content 1”, “content”: “Default Dynamic Content”, “filters”: [

{

“content”: “Variation 1”, “filters”: [

{

“glue”: “and”, “field”: “email”, “object”: “lead”, “type”: “email”, “filter”: null, “display”: null, “operator”: “=”

}

]

}

]

}

], “lists”: [], “headers”: [], “grapesjsbuilder”: {

“customMjml”: “<mjml>rn <mj-head>rnt<!– CSS-STYLE –>rnt<mj-style inline="inline"> p, li {margin:0 !important; padding:0; line-height:1.4em;}rnt</mj-style>rn </mj-head>rn <!– BODY –>rn <mj-body background-color="#f4f4f4">rnt<mj-section padding-top="40px" background-color="#ffffff">rnt <mj-column>rntt<mj-text font-size="11px" align="center">rntt <p>rnttt<span data-fr-verified="true"><span data-fr-verified="true" class="atwho-inserted">{webview_text}</span>⁠⁠⁠⁠⁠⁠⁠</span>rntt </p>rntt</mj-text>rntt<mj-spacer>rntt</mj-spacer>rntt<mj-image src="/app/assets/images/placeholder-logo.png?v5214f417" width="70px" padding-bottom="0px" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff">rnt <mj-column width="550px">rntt<mj-text font-size="16px" align="center" font-style="italic" color="#525252">rntt <p>Ok, let’s make an announcementrntt </p>rntt</mj-text>rntt<mj-spacer height="40px">rntt</mj-spacer>rntt<mj-text font-size="24px" align="center" font-weight="700">rntt <p>Start customizing your emailrntt </p>rntt</mj-text>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff" padding-top="0px">rnt <mj-column padding-top="0px">rntt<mj-image src="/app/assets/images/placeholder-image.png?v5214f417" padding-right="0px" padding-left="0px" padding-bottom="0px" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff" padding-top="0px">rnt <mj-column padding-top="0px">rntt<mj-image src="/app/assets/images/placeholder-image.png?v5214f417" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt <mj-column padding-top="0px">rntt<mj-image src="/app/assets/images/placeholder-image.png?v5214f417" padding-top="0px">rntt</mj-image>rnt </mj-column>rnt</mj-section>rnt<mj-section background-color="#ffffff">rnt <mj-column width="550px">rntt<mj-text font-size="16px" align="center">rntt <p>Make your announcements pop with an eye-catching visual, then provide the crucial details for engagement.rntt </p>rntt <p>⁠⁠⁠⁠⁠⁠⁠rnttt<br/>Customize this section by inserting your own images or choosing a striking solid color backdrop.rntt </p>rntt</mj-text>rntt<mj-spacer height="30px">rntt</mj-spacer>rntt<mj-divider border-width="2px" border-color="#d0d0d0">rntt</mj-divider>rntt<mj-spacer height="30px">rntt</mj-spacer>rntt<mj-text font-size="22px" font-weight="700">rntt <p>Lead with an eye-catching titlerntt </p>rntt</mj-text>rntt<mj-text font-size="16px">rntt <p>Present your news in a brief paragraph. For crucial points, use a bulleted list:rntt </p>rntt <ul>rnttt<li>rnttt <span class="ck-list-bogus-paragraph"><span class="ck-list-bogus-paragraph">What’s on offer</span></span>rnttt</li>rnttt<li>rnttt <span class="ck-list-bogus-paragraph"><span class="ck-list-bogus-paragraph">Where to find us</span></span>rnttt</li>rnttt<li>rnttt <span class="ck-list-bogus-paragraph"><span class="ck-list-bogus-paragraph">Timing specifics</span></span>rnttt</li>rntt </ul>rntt <p>Be concise to motivate readers to explore your website for the full story.rntt </p>rntt</mj-text>rntt<mj-button href="https://" background-color="#000000" inner-padding="16px 32px" border-radius="0px 0px 0px 0px" font-size="16px" align="left">Buttonrntt</mj-button>rntt<mj-spacer align="center">rntt</mj-spacer>rnt </mj-column>rnt</mj-section>rnt<mj-section padding-top="0" padding-bottom="20px" background-color="#000000">rnt <mj-column>rntt<mj-spacer height="40px">rntt</mj-spacer>rntt<mj-image src="/app/assets/images/placeholder-logo-inverse.png?v5214f417" width="70px" padding-bottom="0px">rntt</mj-image>rntt<mj-spacer>rntt</mj-spacer>rntt<mj-text font-family="Ubuntu, Helvetica, Arial, sans-serif" line-height="1.5" align="center" padding-top="0px" padding-bottom="0px" font-size="12px" color="white">rntt <p>Amazing Companyrnttt<br/>11111 Beautiful City, 1212 Nice Streetrnttt<br/>Brazilrnttt<br/>rntt </p>rntt</mj-text>rntt<mj-spacer>rntt</mj-spacer>rntt<mj-text font-size="11px" align="center" color="#a1a1a1">rntt <p>Fancy seeing you down here. You’re getting this email because you gave us your email address.rntt </p>rntt <p>Want to change how you receive these emails?rntt </p>rntt</mj-text>rntt<mj-text font-size="11px" align="center" color="#a1a1a1">rntt <p>rnttt<span data-fr-verified="true"><span data-fr-verified="true" class="atwho-inserted">{unsubscribe_text}</span>⁠⁠⁠⁠⁠⁠⁠</span>rntt </p>rntt</mj-text>rntt<mj-spacer>rntt</mj-spacer>rnt </mj-column>rnt</mj-section>rn </mj-body>rn</mjml>rn”

}

}, // …

}

}

Properties

Name

Type

Description

total

integer

Total count of Emails

emails

array

A mapped collection of Emails indexed by their ID

For the rest of the properties, refer to Email properties.

Create Email

Creates a new Email.

<?php

$data = array(
    'name'             => 'Email created via API', // Required
    'subject'          => 'Hello World!',          // Required
    'language'         => 'en',                    // Required
    'lists'            => array(1, 2),             // Required
    'emailType'        => 'list',
    'isPublished'      => true,
    'customHtml'       => '<h1>Hello from API!</h1>',
    'preheaderText'    => 'Check out our latest update',
    'assetAttachments' => array(5),
);

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

HTTP request

POST /emails/new

POST parameters

    • Name

      • Type

      • Description

      • name

      • string

      • Required.

        邮件名称

      • subject

      • string

      • Required.

        邮件主题

      • language

      • string

      • Required.

        邮件的语言代码，例如 en、fr 等。

      • lists

      • array

      • Required.

        接收邮件的分段数组

      • isPublished

      • boolean

      • 邮件发布状态

      • category

      • integer

      • 邮件所属类别的 ID

      • fromAddress

      • string

      • 发件人邮箱地址

      • fromName

      • string

      • 发件人姓名

      • replyToAddress

      • string

      • 回复目标邮箱地址

      • bccAddress

      • string

      • 抄送 (BCC) 邮箱地址

      • useOwnerAsMailer

      • boolean

      • 使用联系人拥有者作为发件人状态 - 设置为 1 或 true 以使用联系人拥有者作为发件人。

      • utmTags

      • associative array

      • 邮件 UTM 标签的关联数组

      • preheaderText

      • string

      • 出现在主题行之后的摘要文本

      • customHtml

      • string

      • 邮件的自定义 HTML 内容

      • plainText

      • string

      • 邮件的纯文本版本

      • template

      • string

      • 用于设置邮件样式的模板

      • emailType

      • string

      • 邮件类型 - list 或 template

      • publishUp

      • datetime

      • 邮件的激活日期和时间

      • publishDown

      • datetime

      • 邮件的停用日期和时间

      • publicPreview

      • boolean

      • 公开预览状态

      • assetAttachments

      • array

      • 附加到邮件的资产 ID 数组

      • unsubscribeForm

      • integer

      • 邮件的退订表单 ID

      • dynamicContent

      • array

      • 动态内容变体数组

      • headers

      • array

      • 自定义头部数组

Response

  • 当请求成功创建邮件时，返回 201 Created。

响应是一个类似于 Get Email 的 JSON 对象。

Properties

请参考 Email properties。

Edit Email

编辑邮件。

此操作支持 PUT 或 PATCH，具体取决于所需的行为：

  • PUT: 完全替换。 如果 ID 缺失，则请求会创建一个新的邮件。 如果 ID 存在，则请求会清除所有现有数据并用提供的值进行替换。

  • PATCH: 部分更新。 请求仅根据请求数据更新字段值。 如果邮件 ID 不存在，则请求失败。

<?php

$id   = 1;
$data = array(
    'name'    => 'New email name',
    'subject' => 'New subject line',
);
// Create a new Email if ID 1 isn’t found

$createIfNotFound = true;

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

HTTP request

  • PUT /emails/ID/edit: updates an existing Email or creates a new one when the ID doesn’t exist.

  • PATCH /emails/ID/edit: updates an existing Email. The request fails when the ID doesn’t exist.

POST parameters

Accepts the same parameters as those described in Create Email. All parameters are optional.

Response

  • PUT: returns 200 OK when the request successfully updates the Email or 201 Created when the request creates an Email.

  • PATCH: returns 200 OK when the request successfully updates the Email or 404 Not Found error when the Email ID doesn’t exist.

The response is a JSON object similar to Get Email.

Properties

Refer to Email properties.

Delete Email

Deletes an Email.

<?php

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

HTTP request

DELETE /emails/ID/delete

Response

  • Returns 200 OK when the request successfully deletes the Email.

The response is a JSON object containing the data of the deleted Email, similar to Get Email.

Properties

Refer to Email properties.

Send Email to Contact

Sends an Email to a specific Contact.

<?php

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

Tokens

You can send custom tokens to the Email via the tokens parameter. Use the format {token_name} for tokens within the Email content.

<?php

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

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

HTTP request

POST /emails/ID/contact/CONTACT_ID/send

Parameters

Name

Type

Description

tokens

associative array

Associative array of tokens to replace in the Email content

Response

  • Returns 200 OK when the request successfully delivers the Email to the Contact.

{
    "success": true
}

Send Email to Segment

Sends an Email to the Contacts in the Email’s assigned Segments or to specific Segment IDs.

<?php

// Send to all Contacts in the Email's assigned Segments
$response = $emailApi->send($id);
// 发送到特定分段(Segment)

$response = $emailApi->sendToLists($id, $listIds);

HTTP 请求

POST /emails/ID/send

参数

名称

类型

描述

listIds

array

要针对的目标分段 ID 数组。此参数会覆盖电子邮件分配的分段。

响应

  • 当请求成功将电子邮件发送到目标分段时，返回 200 OK。

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

属性

名称

类型

描述

success

boolean

发送成功状态 - 1 或 true 表示发送成功。

sentCount

integer

成功发送的电子邮件总数。

failedRecipients

integer

未成功发送的电子邮件总数。

创建回复

根据电子邮件统计信息中的跟踪哈希，创建一个对电子邮件的回复。

<?php

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

HTTP 请求

POST /emails/reply/TRACKING_HASH

参数

名称

类型

描述

trackingHash

string

用于跟踪电子邮件统计信息的唯一哈希。

响应

  • 当请求成功创建回复时，返回 201 Created。

{
    "success": true
}