Mailjet JS

概览

欢迎使用Mailjet官方JavaScript SDK，它使用webpack、babel和es5构建。
这可以在node或浏览器中使用。

查看官方Mailjet文档中的所有资源和JS代码示例。

注意：
如果在浏览器中使用，目前由于CORS限制，需要代理与Mailjet API通信。
另外，不要在前端代码中公开您的私有API密钥。

目录

• 文档
  • 兼容性
  • 安装
  • 设置客户端
    • 认证
    • API设置
    • SMS设置
    • 进行首次调用
  • 配置
    • 选项
      • 请求超时
      • 请求头
      • 请求最大正文长度
      • 响应最大内容长度
      • 使用代理
    • 配置
      • API版本控制
      • 主机URL
      • 响应输出
    • 禁用API调用
  • TypeScript
    • 发送邮件示例
    • 发送消息示例
    • 获取联系人示例
    • 我们的外部类型定义
  • 浏览器演示
  • 应用示例
  • 请求示例
    • 基本API
      • POST请求
        • 简单POST请求
        • 使用操作
      • GET请求
        • 检索所有对象
        • 使用过滤
        • 检索单个对象
      • PUT请求
      • DELETE请求
    • SMS 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 - 设置自定义主机 URL
• version - 为特定端点设置所需的 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/ 上运行。

---

应用示例

以下是在不同环境中构建的基本应用列表:

1. 浏览器 - 使用 RequireJS 的基本应用，提供可以发出一些请求的页面
2. Node - 包含一些请求的简单脚本的基本应用
3. Sendmail - 基于 ExpressJS 的应用，允许检索联系人列表并向某人发送电子邮件
4. ReactJS - 基于 ReactJS 的应用，提供可以发出一些请求的页面
5. 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脚本包含所有基本的初始化步骤：

1. npm install - 安装所有依赖
2. npm run ts:patch - 为正确构建TypeScript声明文件而修补TS编译器
3. 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上发布更改。