Mailjet JS
概览
欢迎使用Mailjet官方JavaScript SDK,它使用webpack
、babel
和es5
构建。
这可以在node或浏览器中使用。
查看官方Mailjet文档中的所有资源和JS代码示例。
注意:
如果在浏览器中使用,目前由于CORS限制,需要代理与Mailjet API通信。
另外,不要在前端代码中公开您的私有API密钥。
目录
文档
兼容性
此库官方支持以下Node.JS
版本:
- >=
v12.x
安装
使用以下代码安装SDK:
npm install node-mailjet
设置客户端
认证
Mailjet Email API
使用您的公钥
和私钥
进行认证。
export MJ_APIKEY_PUBLIC='您的API密钥'
export MJ_APIKEY_PRIVATE='您的API密钥'
export MJ_API_TOKEN='您的API令牌'
注意:
对于SMS API
,授权基于Bearer令牌。
有关详细信息,请参阅自述文件中的SMS API部分。
基本设置
接下来,导入模块并初始化您的Mailjet客户端:
const Mailjet = require('node-mailjet');
对于EMAIL API
和SEND API
:
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC || '您的API密钥',
apiSecret: process.env.MJ_APIKEY_PRIVATE || '您的API密钥'
});
对于SMS API
:
const mailjet = new Mailjet({
apiToken: process.env.MJ_API_TOKEN || '您的API令牌'
});
API设置
对于EMAIL API
和SEND API
,您可以使用静态方法apiConnect
:
const mailjet = Mailjet.apiConnect(
process.env.MJ_APIKEY_PUBLIC,
process.env.MJ_APIKEY_PRIVATE,
{
config: {},
options: {}
}
);
SMS设置
对于SMS API
,您可以使用静态方法smsConnect
:
const mailjet = Mailjet.smsConnect(
process.env.MJ_API_TOKEN,
{
config: {},
options: {}
}
);
进行首次调用
以下是如何发送电子邮件的示例:
const Mailjet = require('node-mailjet');
const mailjet = Mailjet.apiConnect(
process.env.MJ_APIKEY_PUBLIC,
process.env.MJ_APIKEY_PRIVATE,
);
const request = mailjet
.post('send', { version: 'v3.1' })
.request({
Messages: [
{
From: {
Email: "pilot@mailjet.com",
Name: "Mailjet Pilot"
},
To: [
{
Email: "passenger1@mailjet.com",
Name: "passenger 1"
}
],
Subject: "Your email flight plan!",
TextPart: "Dear passenger 1, welcome to Mailjet! May the delivery force be with you!",
HTMLPart: "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3><br />May the delivery force be with you!"
}
]
})
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
配置
要实例化库,您可以使用以下构造函数:
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
config: CONFIG,
options: OPTIONS
});
const request = mailjet
.METHOD(RESOURCE, CONFIG)
.request(DATA, PARAMS, PERFORM_API_CALL)
METHOD
:您想为此调用使用的方法(post
、put
、get
、delete
之一)RESOURCE
:您想调用的API端点OPTIONS
:描述连接选项的关联数组(完整列表请参见下面的选项)CONFIG
:描述连接配置的关联数组(完整列表请参见下面的配置)DATA
:作为请求主体发送的数据(仅适用于post
、put
、delete
方法)PARAMS
:与请求一起发送的URL参数PERFORM_API_CALL
:确定是否需要进行本地或实际请求的布尔参数
选项
options
具有以下结构:
headers
- 描述您可以传递给请求的附加头字段的关联数组timeout
- 指定请求超时前的毫秒数proxy
- 定义要重定向所有请求的代理服务器的主机名、端口和协议(仅Node选项)maxBodyLength
- 定义允许的http请求内容的最大大小(以字节为单位)(仅Node选项)maxContentLength
- 定义允许的http响应内容的最大大小(以字节为单位)(仅Node选项)
您可以在初始化client
时传递options
,这些options
将用于每个request
:
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
options: {
timeout: 1000,
maxBodyLength: 1500,
maxContentLength: 100,
headers: {
'X-API-Key': 'foobar',
},
proxy: {
protocol: 'http',
host: 'www.test-proxy.com',
port: 3100,
}
}
});
有关更详细的信息,请访问此文档。
请求超时
您可以使用timeout
参数为请求设置超时。
timeout
参数描述请求超时前的毫秒数。
如果请求时间超过timeout
,请求将被中止。
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
options: {
timeout: 100
}
});
const request = mailjet
.post('send', { version: 'v3.1' })
请求头
您可以使用headers
参数为请求设置附加头。
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
options: {
headers: {
Accept: 'application/json',
'API-Key': 'foobar',
'Content-Type': 'application/json'
}
}
});
const request = mailjet
.post('send', { version: 'v3.1' })
请求最大正文长度
您可以使用maxBodyLength
参数设置请求允许的http请求内容的最大大小(以字节为单位)。
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
options: {
maxBodyLength: 100
}
});
const request = mailjet
.post('send', { version: 'v3.1' })
注意:
此参数仅在NodeJS
端工作
响应最大内容长度
您可以使用maxContentLength
参数设置允许的http响应内容的最大大小(以字节为单位)。
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
options: {
maxContentLength: 50
}
});
const request = mailjet
.post('send', { version: 'v3.1' })
注意:
此参数仅在NodeJS
端工作
使用代理
proxy
参数允许您定义代理服务器的主机名、端口、身份验证和协议,以通过它发送API请求:
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
options: {
proxy: {
protocol: 'https',
host: '127.0.0.1',
port: 8080,
auth: {
username: 'test',
password: 'password'
}
}
}
});
const request = mailjet
.post('send', { version: 'v3.1' })
注意:
此参数仅在NodeJS
端有效
配置
config
具有以下结构:
host
- 设置自定义主机 URLversion
- 为特定端点设置所需的 API 版本 (可选v3
、v3.1
、v4
)output
- 指示服务器将响应的数据类型
您可以在初始化 client
时传递 config
,此 config
将用于每个 request
:
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE,
config: {
host: 'api.mailjet.com',
version: 'v3',
output: 'text',
}
});
也可以为每个 request
手动设置 (此 config
的优先级高于传递给 client
的配置):
const request = mailjet
.post('send', {
host: 'api.mailjet.com',
version: 'v3.1',
output: 'json',
})
API 版本控制
Mailjet API 分为三个不同的版本:
v3
-Email API
v3.1
-Email Send API v3.1
,这是我们Send API
的最新版本v4
-SMS API
由于大多数 Email API
端点位于 v3
下,它被设置为默认版本,在发出请求时无需指定。
对于其他版本,您需要使用 version
参数指定版本。
例如,如果使用 Send API
v3.1
:
const request = mailjet
.post('send', { version: 'v3.1' })
更多信息请参阅我们的 API 参考。
主机 URL
Mailjet API 的默认基本主机名是 api.mailjet.com
。
您可以通过在调用中设置 host
的值来修改此主机 URL:
const request = mailjet
.post('send', { version: 'v3.1', host: 'api.us.mailjet.com' })
如果您的帐户已移至 Mailjet 的
US
架构,您需要设置的host
值为api.us.mailjet.com
。
响应输出
Mailjet API 的默认响应输出是 json
。
您可以通过在调用中设置 output
的值来修改此响应输出数据:
const request = mailjet
.post('send', { version: 'v3.1', output: 'arraybuffer' })
output
参数允许您指定响应数据的类型:
arraybuffer
document
json
(默认)text
stream
blob
(仅浏览器选项)
禁用 API 调用
默认情况下,API 调用参数始终启用。
但是,在测试期间您可能希望禁用它以防止对 Mailjet API 进行不必要的调用。
这可以通过将 performAPICall
参数值设置为 false
传递给 .request(data, params, performAPICall)
方法来实现:
const request = mailjet
.post('send', { version: 'v3.1' })
.request({}, {}, false)
TypeScript
当前库基于 TypeScript
并为 Mailjet 类型提供完整覆盖。
所有类型都可以从主入口点 'node-mailjet'
导出:
import {
Contact,
SendEmailV3,
SendEmailV3_1,
Message,
Segmentation,
Template,
SendMessage,
Webhook
} from 'node-mailjet';
该库还有一个通用方法 Request.request<TResult>(data, params, performAPICall)
,可与这些类型一起使用。
发送邮件示例
import { Client, SendEmailV3_1, LibraryResponse } from 'node-mailjet';
const mailjet = new Client({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
(async () => {
const data: SendEmailV3_1.Body = {
Messages: [
{
From: {
Email: 'pilot@test.com',
},
To: [
{
Email: 'passenger@test.com',
},
],
TemplateErrorReporting: {
Email: 'reporter@test.com',
Name: 'Reporter',
},
Subject: 'Your email flight plan!',
HTMLPart: '<h3>Dear passenger, welcome to Mailjet!</h3><br />May the delivery force be with you!',
TextPart: 'Dear passenger, welcome to Mailjet! May the delivery force be with you!',
},
],
};
const result: LibraryResponse<SendEmailV3_1.Response> = await mailjet
.post('send', { version: 'v3.1' })
.request(data);
const { Status } = result.body.Messages[0];
})();
response
将具有以下形状:
{
response: Response;
body: {
Messages: Array<{
Status: string;
Errors: Array<Record<string, string>>;
CustomID: string;
...
}>;
}
}
发送消息示例
import * as Mailjet from 'node-mailjet'; // 另一种可能的导入选项
const mailjet = new Mailjet.Client({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
(async () => {
const body: Mailjet.SendMessage.Body = {
From: 'some@email.com',
To: 'some2@email.com',
Text: 'Test'
};
const result: Mailjet.LibraryResponse<Mailjet.SendMessage.Response> = await mailjet
.post('contact', { version: 'v3' })
.request(body);
const { Status } = result.body;
})();
response
将具有以下形状:
{
response: Response;
body: {
From: string;
To: string;
Text: string;
MessageID: string | number;
SMSCount: number;
CreationTS: number;
SentTS: number;
Cost: {
Value: number;
Currency: string;
};
Status: {
Code: number;
Name: string;
Description: string;
};
}
}
获取联系人示例
import { Client, Contact, LibraryResponse } from 'node-mailjet'
const mailjet = new Client({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
(async () => {
const queryData: Contact.GetContactQueryParams = {
IsExcludedFromCampaigns: false,
Campaign: 2234234,
};
const result: LibraryResponse<Contact.GetContactResponse> = await mailjet
.get('contact', { version: 'v3' })
.request({}, queryData);
const ContactID = result.body.Data[0].ID;
})();
response
将具有以下形状:
{
response: Response;
body: {
Count: number;
Total: number;
Data: Array<{
ID: number;
IsExcludedFromCampaigns: boolean;
Name: string;
CreatedAt: string;
DeliveredCount: number;
Email: string;
...
}>;
}
}
我们的外部类型定义
对于库的早期版本 (3.*.*
及以下),您可以使用 @types/node-mailjet
依赖项。
这些 类型
已发布在 npm
上并可以使用。
这里 是 npm
页面。
如果有遗漏或您有改进建议,请随时请求更改。
浏览器演示
要运行演示,您需要在本地安装并运行 http-proxy
。
使用以下命令安装:
npm install -g http-proxy
然后从 mailjet-apiv3-nodejs
目录运行以下命令:
http-server -p 4001 --proxy="https://api.mailjet.com"
演示应该在 http://0.0.0.0:4001/examples/ 上运行。
应用示例
以下是在不同环境中构建的基本应用列表:
- 浏览器 - 使用
RequireJS
的基本应用,提供可以发出一些请求的页面 - Node - 包含一些请求的简单脚本的基本应用
- Sendmail - 基于
ExpressJS
的应用,允许检索联系人列表并向某人发送电子邮件 - ReactJS - 基于
ReactJS
的应用,提供可以发出一些请求的页面 - Firebase - 基于
Firebase
的应用,提供用于发送 hello world 电子邮件 和基于动态查询字符串数据发送 电子邮件 的Firebase Functions
注意: 对于
浏览器
端示例,目前由于 CORS 限制,需要代理与 Mailjet API 通信。
请求示例
基本 API
POST
请求
使用 Mailjet 客户端的 post
方法:
const request = mailjet
.post($RESOURCE, $CONFIG)
.id($ID)
.request($DATA, $PARAMS, $PERFORM_API_CALL)
.request
参数 $DATA
将包含 POST
请求的主体。
如果要对特定对象执行操作并需要识别它,则需要定义 .id
。
简单的 POST
请求
创建一个新的联系人:
const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.post('contact')
.request({
Email: "passenger@mailjet.com",
IsExcludedFromCampaigns: true,
Name: "New Contact"
})
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
使用 actions
管理联系人对多个列表的订阅状态:
const { Client } = require('node-mailjet') // 另一种使用解构的导入选项
const mailjet = new Client({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.post('contact')
.id($contactID)
.action('managecontactslists')
.request({
ContactsLists: [
{
ListID: $listID,
Action: "addnoforce"
}
]
})
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
GET
请求
使用Mailjet客户端的get
方法:
const request = mailjet
.get($RESOURCE, $CONFIG)
.id($ID)
.request($DATA, $PARAMS, $PERFORM_API_CALL)
.request
参数$PARAMS
将包含应用于请求的任何查询参数。
如果你想检索特定对象,需要定义.id
。
检索所有对象
检索所有联系人:
const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.get('contact')
.request()
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
使用过滤
检索所有不在营销排除列表中的联系人:
const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.get('contact')
.request({}, { IsExcludedFromCampaigns: false })
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
检索单个对象
通过ID
检索特定联系人:
const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.get('contact')
.id($contactID)
.request()
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
PUT
请求
使用Mailjet客户端的put
方法:
const request = mailjet
.put($RESOURCE, $CONFIG)
.id($ID)
.request($DATA, $PARAMS, $PERFORM_API_CALL)
你需要定义.id
来指定要编辑的对象。
.request
参数$DATA
将包含PUT
请求的主体。
Mailjet API中的PUT
请求将作为PATCH
请求工作 - 更新只会影响指定的属性。
现有资源的其他属性既不会被修改,也不会被删除。
这也意味着所有非强制属性都可以从你的有效载荷中省略。
更新联系人的联系人属性:
const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.put('contactdata')
.id($contactID)
.request({
Data: [
{
first_name: "John",
last_name: "Smith"
}
]
})
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
DELETE
请求
使用Mailjet客户端的delete
方法:
const request = mailjet
.delete($RESOURCE, $CONFIG)
.id($ID)
.request($DATA, $PARAMS, $PERFORM_API_CALL)
你需要定义.id
来指定要删除的对象。
.request
参数$DATA
应该为空。
成功的DELETE
请求响应将不包含响应主体,只有一个204 No Content
响应代码。
删除一个电子邮件模板:
const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
const request = mailjet
.delete('template')
.id($templateID)
.request()
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
SMS API
令牌认证
SMS API
端点的认证使用Bearer令牌
完成。
Bearer令牌
在你的Mailjet账户的SMS部分生成。
const Mailjet = require('node-mailjet');
const mailjet = Mailjet.smsConnect(process.env.MJ_API_TOKEN);
示例请求
这是一个SMS API
请求示例:
const Mailjet = require('node-mailjet');
const mailjet = Mailjet.smsConnect(process.env.MJ_API_TOKEN, {
config: {
version: 'v4'
}
});
const request = mailjet
.post('sms-send')
.request({
Text: "祝你在Mailjet的短信航班愉快!",
To: "+33600000000",
From: "MJPilot"
})
request
.then((result) => {
console.log(result.body)
})
.catch((err) => {
console.log(err.statusCode)
})
开发
Mailjet喜欢开发者。你可以成为这个项目的一部分! 这个SDK是开源世界的一个很好的介绍,请查看代码!
随时提问,并贡献:
- Fork这个项目。
- 创建一个新分支。
- 实现你的功能或修复bug。
- 为其添加文档。
- 提交,推送,打开一个拉取请求,就是这样。
如果你有改进指南的建议,请在我们的官方API文档仓库提交一个问题。
要求
- 需要
Node.JS
>= 4.x
使用以下命令初始化包:
npm run init
其中init
脚本包含所有基本的初始化步骤:
npm install
- 安装所有依赖npm run ts:patch
- 为正确构建TypeScript
声明文件而修补TS
编译器npm run pkg:prepare
- 为git hooks
安装husky
构建
为发布目的构建(包括最小化):
npm run build
为开发目的构建(不包括最小化):
npm run build:dev && npm run build:prepublish
构建以进行监视和热重载:
npm run build:watch
测试
执行所有测试:
npm run test
监视测试:
npm run test:watch
获取测试覆盖率:
npm run cover
要使用npm link
在本地测试新功能,请使用npm脚本npm run pkg:link
。
这是为了正确导出d.ts
文件所需的。
合并更改
在PR合并之前,检查提交信息是否会正确添加到CHANGELOG.md
文件中:
npm run release:dry
这也允许查看包版本是否按照SemVer
约定正确增加。
然后运行:
npm run release
**重要:**如果包版本增加不正确,你应该手动使用这些脚本:
npm run release:patch
npm run release:minor
npm run release:major
CI过程目前不工作,所以请手动运行
npm run test
发布过程
在feature
分支经过测试并合并到master
后进行发布。
首先,检出master
并pull
最新的提交。
git checkout master
git pull
接下来,运行npm run release
。
之后,cd ./dist
然后运行npm login
和npm publish
以在npm上发布更改。