发送相关
普通发送
URL
https://email.api.engagelab.cc/v1/mail/send
Content-Type
Content-Type: application/json;charset=utf-8
HTTP 请求方式
POST
请求 Header
Header | 类型 | 必须 | 说明 |
---|---|---|---|
Authorization | String | true | Basic base64(api_user:api_key) |
Body 参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
from | string | 是 | 发件人。举例:support@mail.engagelab.com ,support<support@mail.engagelab.com> 。 |
to | array[string] | 是 | 收件人。最大支持 100 个地址。如 ["xjm@hotmail.com","xjm2@gmail.com"] |
body | object | 是 | 邮件设置 |
custom_args | object | 否 | 客户自定义的可选字段,最大支持 1KB。 |
request_id | string | 否 | 本次发送请求 ID;最大支持 128 字符。 |
cc | array[string] | 否 | 抄送地址。最大支持 100 个地址。仅 send_mode = 1 时,本参数有效。 |
bcc | array[string] | 否 | 密送地址。最大支持 100 个地址。仅 send_mode = 1 时,本参数有效。 |
reply_to | array[string] | 否 | 回复地址。最大支持 3 个地址;如果不传值,则回复邮件地址为 from。 |
subject | string | 是 | 邮件主题。最大 256 字符;支持变量、emoji。 |
content | object | 是 | 邮件正文。 |
html | string | * | 邮件的内容。邮件格式为 text/html。 |
text | string | * | 邮件的内容。 邮件格式为 text/plain。 |
preview_text | string | 否 | 邮件摘要 |
vars | object | 否 | 变量。最大支持 1MB;仅 send_mode=0 时,本参数有效。 |
label_id | string | 否 | 本次发送所使用的标签 ID |
headers | object | 否 | 邮件头部信息。最大 1KB。 |
attachments | array[object] | 否 | 邮件附件。总大小不得超过 10MB。 |
content | string | 是 | 附件内容 base64 编码。 |
filename | string | 是 | 附件文件名,例如:example.pdf。 |
disposition | string | 是 | 值允许 attachment、inline。 |
content_id | string | 否 | 如果 disposition 的值为 inline, 文件类型为 image , 则需要设置该值。 |
settings | object | 否 | 发送设置。 |
send_mode | int | 否 | 发送方式。 0 表示单独发送;1 表示广播发送,所有收件人会同时显示;2 表示地址列表发送,to 的值为地址列表别称。 默认为 0。 |
return_email_id | boolean | 否 | 是否返回 email ID,默认 true。 |
sandbox | boolean | 否 | 是否使用沙箱模式,默认 false。如果为 true, 邮件不会被投递,只会验证请求参数是否合法。 |
notification | boolean | 否 | 是否使用已读回执,默认 false。默认回执到 from,需要和收信路由配合使用。 |
open_tracking | boolean | 否 | 是否开启 open 追踪,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
click_tracking | boolean | 否 | 是否开启 click 追踪,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
unsbuscribe_tracking | boolean | 否 | 是否开启取消订阅,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
unsubscribe_page_id | array[int] | 否 | 自定义取消订阅页面,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
注意:
1. send_mode=2 时,to 的值为地址列表别称,个数不能超过 5 个,且此时参数 cc、bcc 失效。
2. html 和 plain 不能同时为空。
3. preview_text 只能和 html 一起使用,如果不传 html 的值,preview_text 的值不会生效。
4.
vars 用于邮件内容的变量替换,格式为 json 对象,格式为{"varname":["value1,"value2"]}
,其中 varname 为邮件内容变量。
邮件内容为:亲爱的%name%,欢迎使用%sp%邮件服务。
对应 vars 传值:{"name":["mike"], "sp":["engagelab"]}
邮件内容替换:亲爱的 mike,欢迎使用 engagelab 邮件服务。
5.
headers 用于自定义邮件的头域,格式为 json 对象,格式为{"User-Define":"123", "User-Custom":"abc"}
。但是 key 的字符串不能包含以下值(不区分大小写)
DKIM-Signature
,Received
,Sender
,Date
,From
,To
,Reply-To
,Cc
,Bcc
,Subject
,Content-Type
,
Content-Transfer-Encoding
,X-SENDCLOUD-UUID
,X-SENDCLOUD-LOG
,X-Remote-Web-IP
,X-SMTPAPI
, Return-Path
,X-SENDCLOUD-LOG-NEW
6. disposition 被设置为 inline 时,附件内容是图片,附件会作为内联图片直接在邮件正文中渲染显示。content_id 必须设置且唯一字符串,作为图片在邮件正文中显示时的 src。
邮件正文:
<html>
<img src="cid:image_1000"></img>
<img src="cid:image_1001"></img>
</html>
attachments 参数:
[
{"content":" base 64 image content", "filename": "a23456.jpg","disposition": "inline","content_id": "image_1000"},
{"content":" base 64 image content", "filename": "a23457.jpg","disposition": "inline","content_id": "image_1001"},
]
7. customer_args 作为客户自定义内容,会在邮件头埋点;后续的 WebHook 数据中,会回传给客户 。
8. request_id 为防止重复提交,有效期 1 小时。若 1 小时内重复提交,将返回上次请求结果。
9. 邮件总大小不能超过 70MB。
请求示例
curl -X POST -H 'Content-Type: application/json; charset=utf-8'
-H 'Authorization: YXBpX3VzZXI6YXBpX2tleQ=='
--data '{
"from": "EngageLab Newsletter <newsletter@mail.engagelab.com>",
"to": ["111@qq.com", "222<222@qq.com>"],
"body": {
"cc": ["noreply@mail.engagelab.com"],
"bcc": ["intern<intern@mail.engagelab.com>"],
"reply_to": ["reply@mail.engagelab.com"],
"subject": "%date% Newsletter ",
"content": {
"html": "<a href=\"https://www.engagelab.com\">Newsletter %kkk%</a>",
"text": "Today's news is %ttt%",
"preview_text": "preview_text is ..."
},
"vars": { },
"label_id": 100233,
"headers": {},
"attachments": [{
"content": "The Base64 encoded content of the attachment",
"filename": "The attachment's filename",
"disposition": "inline | attachment",
"content_id": ""
}],
"settings": {
"send_mode": 0,
"return_email_id": true,
"sandbox": false,
"notification": false,
"open_tracking": true,
"click_tracking": false,
"unsubscribe_tracking": true,
"unsubscribe_page_id": [1,2]
}
},
"custom_args": {},
"request_id": ""
}' 'https://email.api.engagelab.cc/v1/mail/send'
响应示例
- 非地址列表发送 (send_mode=0 或 send_mode=1)
Response-success
HTTP Status: 200
{
"email_ids":[
"1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$111@qq.com",
"1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$222@qq.com"],
"request_id":""
}
Response-error
HTTP Status :401
{
"code": 30801,
"message": "From can not be empty"
}
- 地址列表发送 (send_mode=2)
Response-success
HTTP Status: 200
{
"task_id":[102923],
"request_id":""
}
Response-error
HTTP Status :400
{
"code": 30801,
"message": "From can not be empty"
}
模板发送
URL
https://email.api.engagelab.cc/v1/mail/sendtemplate
Content-Type
Content-Type: application/json; charset=utf-8
HTTP 请求方式
POST
请求 Header
Header | 类型 | 必须 | 说明 |
---|---|---|---|
Authorization | String | true | Basic base64(api_user:api_key) |
Query 参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
from | string | 是 | 发件人。举例:support@mail.engagelab.com ,support<support@mail.engagelab.com> 。 |
to | array[string] | 是 | 收件人。最大支持 100 个地址。如 ["xjm@hotmail.com","xjm2@gmail.com"] |
body | object | 是 | 邮件设置 |
custom_args | object | 否 | 客户自定义的可选字段,最大支持 1KB。 |
request_id | string | 否 | 本次发送请求 ID;最大支持 128 字符。 |
body 参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
cc | array[string] | 否 | 抄送地址。最大支持 100 个地址。仅 send_mode = 1 时,本参数有效。 |
bcc | array[string] | 否 | 密送地址。最大支持 100 个地址。仅 send_mode = 1 时,本参数有效。 |
reply_to | array[string] | 否 | 回复地址。最大支持 3 个地址;如果不传值,则回复邮件地址为 from。 |
subject | string | 否 | 邮件主题。最大 256 字符;支持变量、emoji。若填写将覆盖调用模板的主题。 |
template_invoke_name | string | 是 | 模板调用名称。 |
vars | object | 否 | 变量。最大支持 1MB;仅 send_mode=0 时,本参数有效。 |
label_id | string | 否 | 本次发送所使用的标签 ID。 |
headers | object | 否 | 邮件头部信息。最大 1KB。 |
attachments | array[object] | 否 | 附件设置。 |
content | string | 是 | 附件内容 base64 编码。 |
filename | string | 是 | 附件文件名,例如:example.pdf。 |
disposition | string | 是 | 值允许 attachment、inline。 |
content_id | string | 否 | 如果 disposition 被设置为 inline,文件类型为 image,需要设置该值。 |
settings | object | 否 | 发送设置。 |
send_mode | int | 否 | 发送方式。0 表示单独发送;1 表示广播发送,所有收件人会同时显示;2 表示地址列表发送,to 的值为地址列表别称。默认为 0。 |
return_email_id | boolean | 否 | 是否返回 email ID,默认 true。 |
sandbox | boolean | 否 | 是否使用沙箱模式,默认 false。如果为 true,邮件不会被投递,只会验证请求参数是否合法。 |
notification | boolean | 否 | 是否使用已读回执,默认 false。默认回执到 from,需要和收信路由配合使用。 |
open_tracking | boolean | 否 | 是否开启 open 追踪,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
click_tracking | boolean | 否 | 是否开启 click 追踪,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
unsbuscribe_tracking | boolean | 否 | 是否开启取消订阅。默认系统设置值。仅 send_mode=0 时,本参数有效。 |
unsubscribe_page_id | array[int] | 否 | 自定义取消订阅页面,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
注意:
1. send_mode=2 时,to 的值为地址列表别称,个数不能超过 5 个,且此时参数 cc、bcc 失效。
2.
vars 用于邮件内容的变量替换,格式为 json 对象,格式为{"varname":["value1,"value2"]}
,其中 varname 为邮件内容变量。
邮件内容为:亲爱的%name%,欢迎使用%sp%邮件服务。
对应 vars 传值:{"name":["mike"], "sp":["engagelab"]}
邮件内容替换:亲爱的 mike,欢迎使用 engagelab 邮件服务。
3.
headers 用于自定义邮件的头域,格式为 json 对象,格式为{"User-Define":"123", "User-Custom":"abc"}
。但是 key 的字符串不能包含以下值(不区分大小写)
DKIM-Signature
,Received
,Sender
,Date
,From
,To
,Reply-To
,Cc
,Bcc
,Subject
,Content-Type
,
Content-Transfer-Encoding
,X-SENDCLOUD-UUID
,X-SENDCLOUD-LOG
,X-Remote-Web-IP
,X-SMTPAPI
, Return-Path
,X-SENDCLOUD-LOG-NEW
4. disposition 被设置为 inline 时,附件内容是图片,附件会作为内联图片直接在邮件正文中渲染显示。content_id 必须设置且唯一字符串,作为图片在邮件正文中显示时的 src。
邮件正文:
<html>
<img src="cid:image_1000"></img>
<img src="cid:image_1001"></img>
</html>
attachments 参数:
[
{"content":" base 64 image content", "filename": "a23456.jpg","disposition": "inline","content_id": "image_1000"},
{"content":" base 64 image content", "filename": "a23457.jpg","disposition": "inline","content_id": "image_1001"},
]
5.
custom_args 作为客户自定义内容,会在邮件头埋点;后续的 WebHook 数据中,会回传给客户 。
6.
request_id 为防止重复提交,有效期 1 小时。若 1 小时内重复提交,将返回上次请求结果。
7.
邮件总大小不能超过 70MB。
请求示例
month_bill 模板内容
亲爱的%name%:
您好!您本月在爱发信的消费金额为:%money% 元。
模板普通发送示例 ( 调用模板 month_bill )
curl -X POST "https://email.api.engagelab.cc/v1/mail/sendtemplate"
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
--header "Content-Type: application/json"
--data '{
"from": "support@mail.engagelab.com",
"to": ["xjmfc@126.com", "xjmfcme@gmail.com"],
"body": {
"subject": "test email",
"template_invoke_name": "month_bill",
"label_id": 10143,
"vars": {
"%name%": ["jack", "jone"],
"%money%": ["30", "50"]
},
"headers": {
"userdefine-tag-location": "us",
"userdefine-tag-user": "fashion"
},
"attachments": [{
"content": "The Base64 encoded content of the attachment",
"filename": "The attachment's filename",
"disposition": "inline | attachment",
"content_id": ""
}],
"settings": {
"send_mode": 0,
"return_email_id": true,
"sandbox": false,
"notification": false,
"open_tracking": true,
"click_tracking": false,
"unsubscribe_tracking": true,
"unsubscribe_page_id": [1, 2]
}
},
"custom_args": {},
"request_id": ""
}'
#xjmfc@126.com 收到的邮件:
亲爱的 jack:
您好!您本月在爱发信的消费金额为:30 元。
#---------------------------------------------------
# xjmfcme@gmail.com 收到的邮件:
亲爱的 Joe:
您好!您本月在爱发信的消费金额为:50 元。
响应示例
Response-success
HTTP Status: 200
{
"email_ids":[
"1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound0$xjmfc@126.com",
"1447054895514_15555555_32350_1350.sc-10_10_126_221-inbound1$xjmfcme@gmail.com"],
"request_id":""
}
Response-error
HTTP Status :404
not found
模板地址列表发送 ( 调用模板 month_bill , 调用地址列表 users@maillist.email.engagelab.com )
curl -X POST "https://email.api.engagelab.cc/v1/mail/sendtemplate"
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
--header "Content-Type: application/json"
--data '{
"from": "admin@engaelab.com",
"to": ["users@maillist.email.engagelab.com"],
"body": {
"subject": "2022 年 11 月账单",
"template_invoke_name": "month_bill",
"label": "双 11"
}
}'
Response-success
HTTP Status: 200
{
"task_id":[102923],
"request_id":""
}
Response-error
HTTP Status :404
not found
发送会议日历
URL
https://email.api.engagelab.cc/v1/mail/sendcalendar
Content-Type
Content-Type: application/json; charset=utf-8
HTTP 请求方式
POST
请求 Header
Header | 类型 | 必须 | 说明 |
---|---|---|---|
Authorization | String | true | Basic base64(api_user:api_key) |
Query 参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
from | string | 是 | 发件人。举例:support@mail.engagelab.com ,support<support@mail.engagelab.com> 。 |
to | array[string] | 是 | 收件人。最大支持 100 个地址。如 ["xjm@hotmail.com","xjm2@gmail.com"] |
body | object | 是 | 邮件设置 |
custom_args | object | 否 | 客户自定义的可选字段,最大支持 1KB。 |
request_id | string | 否 | 本次发送请求 ID;最大支持 128 字符。 |
body 参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
cc | array[string] | 否 | 抄送地址。最大支持 100 个地址。仅 send_mode = 1 时,本参数有效。 |
bcc | array[string] | 否 | 密送地址。最大支持 100 个地址。仅 send_mode = 1 时,本参数有效。 |
reply_to | array[string] | 否 | 回复地址。最大支持 3 个地址;如果不传值,则回复邮件地址为 from。 |
subject | string | 是 | 邮件主题。最大 256 字符;支持变量、emoji。 |
content | object | 是 | 邮件内容设置。 |
html | string | * | 邮件的内容。邮件格式为 text/html。 |
text | string | * | 邮件的内容。 邮件格式为 text/plain。 |
preview_text | string | 否 | 邮件摘要。 |
vars | object | 否 | 变量。最大支持 1MB;仅 send_mode=0 时,本参数有效。 |
label_id | string | 否 | 本次发送所使用的标签 ID。 |
headers | object | 否 | 邮件头部信息。最大 1KB。 |
attachments | array[object] | 否 | 邮件附件。总大小不得超过 10MB。 |
content | string | 是 | 附件内容 base64 编码。 |
filename | string | 是 | 附件文件名,例如:example.pdf。 |
disposition | string | 是 | 允许值为:inline、attachment。 |
content_id | string | 是 | 如果 disposition 被设置为 inline,文件类型为 image,需要设置该值。 |
settings | object | 否 | 发送设置。 |
send_mode | int | 否 | 发送方式。 0 表示单独发送;1 表示广播发送,所有收件人会同时显示; 默认为 0。 |
return_email_id | boolean | 否 | 返回 email ID,默认 true。 |
sandbox | boolean | 否 | 是否使用沙箱模式,默认 false。如果为 true,邮件不会被投,只会验证请求参数是否合法。 |
notification | boolean | 否 | 是否使用回执,默认 false。默认回执到 from,需要和收信路由配合使用。 |
open_tracking | boolean | 否 | 是否开启 open 追踪,默认系统配置值。仅 send_mode=0 时,本参数有效。 |
click_tracking | boolean | 否 | 是否开启 click 追踪,默认系统配置值。仅 send_mode=0 时,本参数有效。 |
unsbuscribe_tracking | boolean | 否 | 是否开启取消订阅,默认系统配置值。仅 send_mode=0 时,本参数有效。 |
unsubscribe_page_id | array[int] | 否 | 自定义取消订阅页面,默认系统设置值。仅 send_mode=0 时,本参数有效。 |
calendar | object | 是 | 日历设置。 |
time_zone_id | string | 是 | 示例参见 日历时区字典。 |
start_time | string | 是 | 日程开始时间。形如:yyyy-MM-dd HH:mm:ss |
end_time | string | 是 | 日程结束时间。形如:yyyy-MM-dd HH:mm:ss |
title | string | 是 | 会议标题。最大 256 字符。 |
organizer | object | 是 | 组织者。 |
name | string | 否 | 名称。最大 64 字符。 |
string | 是 | 邮箱地址。 | |
location | string | 是 | 会议地点。最大 128 字符。 |
description | string | 否 | 会议描述。最大 1024 字符。 |
participators | array[object] | 否 | 参与者。 |
name | string | 否 | 名字。最大 64 字符 |
string | 是 | 邮箱地址。 | |
alarm_min_before | integer | 否 | 提前多少分钟进行会议提醒。范围 1 ~ 60。 |
action | object | 否 | 日历操作。 |
name | string | 否 | 操作名称。允许值:create,update, cancel。默认值为 create。 |
uid | string | 否 | update 和 cancel 时候需要传递此参数。 uid 值会在 create 日历邮件时接口返回。 |
注意:
1. html 和 plain 不能同时为空。
2. preview_text 只能和 html 一起使用,如果不传 html 的值,preview_text 的值不会生效。
3.
vars 用于邮件内容的变量替换,格式为 json 对象,格式为{"varname":["value1,"value2"]}
,其中 varname 为邮件内容变量。
邮件内容为:亲爱的%name%,欢迎使用%sp%邮件服务。
对应 vars 传值:{"name":["mike"], "sp":["engagelab"]}
邮件内容替换:亲爱的 mike,欢迎使用 engagelab 邮件服务。
4.
headers 用于自定义邮件的头域,格式为 json 对象,格式为{"User-Define":"123", "User-Custom":"abc"}
。但是 key 的字符串不能包含以下值(不区分大小写)
DKIM-Signature
,Received
,Sender
,Date
,From
,To
,Reply-To
,Cc
,Bcc
,Subject
,Content-Type
,
Content-Transfer-Encoding
,X-SENDCLOUD-UUID
,X-SENDCLOUD-LOG
,X-Remote-Web-IP
,X-SMTPAPI
, Return-Path
,X-SENDCLOUD-LOG-NEW
5. disposition 被设置为 inline 时,附件内容是图片,附件会作为内联图片直接在邮件正文中渲染显示。content_id 必须设置且唯一字符串,作为图片在邮件正文中显示时的 src。
邮件正文:
<html>
<img src="cid:image_1000"></img>
<img src="cid:image_1001"></img>
</html>
attachments 参数:
[
{"content":" base 64 image content", "filename": "a23456.jpg","disposition": "inline","content_id": "image_1000"},
{"content":" base 64 image content", "filename": "a23457.jpg","disposition": "inline","content_id": "image_1001"},
]
6.custom_args 作为客户自定义内容,会在邮件头埋点;后续的 WebHook 数据中,会回传给客户 。
7.request_id 为防止重复提交,有效期 1 小时。若 1 小时内重复提交,将返回上次请求结果。
8.邮件总大小不能超过 70MB。
请求示例
curl -X POST 'https://email.api.engagelab.cc/v1/mail/sendcalendar' \
--header 'Authorization: Basic MTIyNF94am06MTJkOGIwODVlNjZhZGUyMmNlNGIwOWI5NjQ2YWQ1ODE=' \
--header 'Content-Type: application/json' \
--data '{
"from": "EngageLab Newsletter <newsletter@mail.engagelab.com>",
"to": ["111@qq.com", "222<222@qq.com>"],
"body": {
"cc": ["noreply@mail.engagelab.com"],
"bcc": ["intern<intern@mail.engagelab.com>"],
"reply_to": ["reply@mail.engagelab.com"],
"subject": "%date% Newsletter ",
"content": {
"html": "<a href=\"https://www.engagelabe.com\">Newsletter %kkk%</a>",
"text": "Newsletter %ttt%",
"preview_text": "preview_text is ..."
},
"label_id": "1233",
"headers": {
"userdefine-tag-location": "us",
"userdefine-tag-user": "fashion"
},
"settings": {
"send_mode": 0,
"return_email_id": true,
"sandbox": false,
"notification": false,
"open_tracking": true,
"click_tracking": false,
"unsubscribe_tracking": true,
"unsubscribe_page_id": [1,2]
},
"calendar": {
"time_zone_id":"America/New_York",
"start_time": "2020-12-10 10:00:00",
"end_time": "2020-12-10 12:00:00",
"title": "meeting titel",
"organizer": {
"name": "David",
"email": "david@mail.engagelab.com"
},
"location": "room208",
"description": "hello",
"alarm_min_before": 5,
"participators": [
{
"name": "p1",
"email": "p1@engagelab.org"
},
{ "email": "p2@engagelab.org", "name": "p2"},
{ "email": "p3@engagelab.org"}
],
"action": {
"name": "create",
"uid": "329r239h239888"
}
}
},
"custom_args": {},
"request_id": ""
}'
响应示例
Response-success
HTTP Status: 200
{
"uid": "20230103T065922Z-uidGen@PC201503200437",
"email_ids": [
"1672729159224_15_2942_8497.sc-10_2_226_96-test0$111@qq.com",
"1672729159224_15_2942_8497.sc-10_2_226_96-test1$222@qq.com"
],
"request_id": ""
}
Response-error
HTTP Status :400
{
"code": 30801,
"message": "From can not be empty"
}