布雷沃节点.js SDK

安装
npm install @getbrevo/brevo
快速启动
import { BrevoClient } from '@getbrevo/brevo';
const brevo = new BrevoClient({
apiKey: 'your-api-key',
});
const result = await brevo.transactionalEmails.sendTransacEmail({
subject: "Hello",
textContent: "Hello world!",
sender: { name: "Sender", email: "[email protected]" },
to: [{ email: "[email protected]" }]
});
console.log('Email sent:', result);
配置
const brevo = new BrevoClient({
apiKey: 'your-api-key',
timeoutInSeconds: 30,
maxRetries: 3,
});
构造选项
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
apiKey | string | null | 你的Brevo API密钥。 见 认证。 。 。 . |
clientId | string | BREVO_CLIENT_ID 环境 var | OAuth 2.0 M2M 应用程序客户端ID |
clientSecret | string | BREVO_CLIENT_SECRET 环境 var | OAuth 2.0 M2M 应用程序客户端秘密 |
token | string | null | 您已经拥有的 OAuth 访问令牌( 未被 SDK 刷新) |
auth | AuthProvider | null | 自定义认证提供者( 动态符号, 密钥旋转) . |
timeoutInSeconds | number | 60 | 默认请求超时( 秒) |
maxRetries | number | 2 | 可重试错误的最大尝试 |
baseUrl | string | null | 覆盖默认 API 基础 URL |
fetch | typeof fetch | null | 自定义获取执行 |
headers | Record<string, string> | null | 每次请求都会发送额外的默认信头 |
logging | LogConfig | Logger | null | 日志配置 |
认证
客户端支持两种认证方法. 每个客户使用一个.
API 密钥
import { BrevoClient } from '@getbrevo/brevo';
const brevo = new BrevoClient({ apiKey: 'xkeysib-xxx' });
在您的 Brevo 账户中创建 API 密钥 app.brevo.com/设定/钥匙/api。见 API 密钥认证。 。 。 .
OAuth 2.0 机对机(M2M)
传递M2M应用程序的客户端身份和秘密. 客户端在第一次请求时将它们交换为访问令牌,重新使用令牌,并在新令牌到期前不久取取取(令牌有效约一小时).
import { BrevoClient } from '@getbrevo/brevo';
const brevo = new BrevoClient({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
});
const account = await brevo.account.getAccount();
或者设定 BREVO_CLIENT_ID 财务报告和审定财务报表 BREVO_CLIENT_SECRET 在环境中创建客户端,没有参数:
const brevo = new BrevoClient();
如果您已经拥有访问符, 请直接通过 。 客户端发送它作为 - 而不是刷新它:
const brevo = new BrevoClient({ token: 'your-access-token' });
客户端要求的标志包含给应用程序的每一个范围. 创建 M2M 应用程序并选择其范围,或者请求带有特定范围的信使,参见 机器对机器(M2M)认证。 。 。 .
处理错误
SDK基于HTTP状态代码抛出特定出错类型.
import { Brevo, BrevoError } from '@getbrevo/brevo';
try {
await brevo.transactionalEmails.sendTransacEmail({...});
} catch (err) {
if (err instanceof Brevo.UnauthorizedError) {
console.error('Invalid API key');
} else if (err instanceof Brevo.TooManyRequestsError) {
const retryAfter = err.rawResponse.headers['retry-after'];
console.error(`Rate limited. Retry after ${retryAfter} seconds`);
} else if (err instanceof BrevoError) {
console.error(`API Error ${err.statusCode}:`, err.message);
}
}
输入的子类在名称空格下 Brevo (例如:. Brevo.UnauthorizedError)——仅 BrevoError 财务报告和审定财务报表 BrevoTimeoutError 属于顶级出口.
错误类型 :
400- 说吧Brevo.BadRequestError401- 说吧Brevo.UnauthorizedError403- 说吧Brevo.ForbiddenError404- 说吧Brevo.NotFoundError422- 说吧Brevo.UnprocessableEntityError429- 说吧Brevo.TooManyRequestsError500+- 说吧Brevo.InternalServerError
错误属性
全体 BrevoError 实例提供:
statusCode: HTTP 状态代码message: 错误消息body: 解析出错反应正文rawResponse: 有信头的原始响应
检索
默认情况下启用了带有指数后退的自动重试(2个重试).
// Client-level
const brevo = new BrevoClient({
apiKey: 'your-api-key',
maxRetries: 3
});
// Request-level
await brevo.transactionalEmails.sendTransacEmail({...}, {
maxRetries: 5
});
可重试状态代码 : 408, (中文(简体) ), 429, (中文(简体) ), 500, (中文(简体) ), 502, (中文(简体) ), 503, (中文(简体) ), 504
复试如何工作
- 指向后退:~1s,~2s,~4s(带有焦急)
- 尊重
Retry-After费率限制页眉 - 可禁用每个请求
maxRetries: 0
超时
默认超时为60秒. 在客户端或请求级别配置 .
// Client-level
const brevo = new BrevoClient({
apiKey: 'your-api-key',
timeoutInSeconds: 30
});
// Request-level
await brevo.transactionalEmails.sendTransacEmail({...}, {
timeoutInSeconds: 10
});
建议值:
- 标准 API 呼叫 :
30-60s(默认) - 快速行动:
10-15s - 散装操作 :
120-300s - 实时 :
5-10s
请求选项
其他信头
await brevo.transactionalEmails.sendTransacEmail({...}, {
headers: {
'X-Custom-Header': 'custom-value'
}
});
查询参数
await brevo.transactionalEmails.sendTransacEmail({...}, {
queryParams: {
'customParam': 'value'
}
});
中止信号
const controller = new AbortController();
await brevo.transactionalEmails.sendTransacEmail({...}, {
abortSignal: controller.signal
});
controller.abort();
原始反应
const { data, rawResponse } = await brevo.transactionalEmails.sendTransacEmail({...})
.withRawResponse();
console.log(rawResponse.headers['X-My-Header']);
二进制响应
const response = await brevo.inboundParsing.getInboundEmailAttachment(...);
// Choose one:
const stream = response.stream();
// const arrayBuffer = await response.arrayBuffer();
// const blob = await response.blob();
// const bytes = await response.bytes();
保存到文件示例
节点.js(可读结构):
import { createWriteStream } from 'fs';
import { Readable } from 'stream';
import { pipeline } from 'stream/promises';
const stream = response.stream();
const nodeStream = Readable.fromWeb(stream);
await pipeline(nodeStream, createWriteStream('path/to/file'));
宾:
await Bun.write('path/to/file', response.stream());
浏览器 :
const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
类型脚本
所有请求和响应类型均被导出.
import { BrevoClient } from '@getbrevo/brevo';
const request: Brevo.SendTransacEmailRequest = {
subject: "First email",
textContent: "Hello world!",
sender: { name: "Bob Wilson", email: "[email protected]" },
to: [{ email: "[email protected]", name: "Sarah Davis" }]
};
日志
import { BrevoClient, logging } from '@getbrevo/brevo';
const brevo = new BrevoClient({
apiKey: 'your-api-key',
logging: {
level: logging.LogLevel.Debug,
logger: new logging.ConsoleLogger(),
silent: false
}
});
自定义日志示例
import winston from 'winston';
const winstonLogger = winston.createLogger({...});
const logger: logging.ILogger = {
debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
info: (msg, ...args) => winstonLogger.info(msg, ...args),
warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
error: (msg, ...args) => winstonLogger.error(msg, ...args),
};
自定义获取客户端
覆盖默认获取高级使用案例的执行 .
const brevo = new BrevoClient({
apiKey: 'your-api-key',
fetch: async (url, options) => {
console.log('→', url);
const response = await fetch(url, options);
console.log('←', response.status);
return response;
},
});
常用案例
使用节点比对 :
import fetch from 'node-fetch';
const brevo = new BrevoClient({
apiKey: 'your-api-key',
fetch: fetch as typeof globalThis.fetch,
});
使用undici :
import { fetch } from 'undici';
const brevo = new BrevoClient({
apiKey: 'your-api-key',
fetch: fetch as typeof globalThis.fetch,
});
使用请求的ID头 :
import { randomUUID } from 'crypto';
const brevo = new BrevoClient({
apiKey: 'your-api-key',
fetch: async (url, options) => {
return fetch(url, {
...options,
headers: {
...options?.headers,
'X-Request-ID': randomUUID(),
},
});
},
});
运行时间相容性
- 节点.js 18+
- 维塞尔
- 云花岗工人
- 德诺v1.25+
- 1.0+号舱
- 原生反应
从v5.x升级
v6是主要发布. 大部分突破性变化来自在Brevo的内部努力,使终点、参数和模型更加完善 自我描述 ——所以名称,形状和需要的字段传达意向而不需要交叉引用外部的docs(既用于开发者,也用于对Brevo API工作的AI代理).
v5.x 继续支持. 如果你需要暂时坚持v5, 把它贴上:
npm install @getbrevo/brevo@^5.0
查看 v5 – v6 迁移指南
中断更改
公司 - getCompanies 过滤参数重命名
// v5
await brevo.companies.getCompanies({ filters: 'foo' });
// v6
await brevo.companies.getCompanies({ 'filters[attributes.name]': 'foo' });
旧的 filters 名称仍然在编译,但过滤器是静默地丢弃的服务器侧并获得未过滤的列表。 审计每个呼叫网站.
事件—— createBatchEvents 有效载外形
// v5
await brevo.event.createBatchEvents([{ /* event */ }]);
// v6
await brevo.event.createBatchEvents({ events: [{ /* event */ }] });
余额 -- -- getActiveBalancesApi 响应参数重命名( t)
- 已替换响应类型 :
BalanceLimit→GetLoyaltyBalanceProgramsPidActiveBalanceResponse。 。 。 . - 参数从蛇 case更名为骆驼Case:
contact_id→contactId, (中文(简体) ),balance_definition_id→balanceDefinitionId, (中文(简体) ),sort_field→sortField。 。 。 .
余额 -- -- getContactBalances 需求 balanceDefinitionId
客户关系管理 - getCrmTasktypes 返回数组 (单位:千美元)GetCrmTasktypesResponseItem[]) (中文(简体) ).
模式字段已删除数字 : GetWebhook.channel, (中文(简体) ), GetProcessResponseInfo.export, (中文(简体) ), GetEventsList.events[].source, (中文(简体) ), GetExtendedCampaignOverview.utmIDActive (替换为: utmID: number) (中文(简体) ).
模型字段重命名数字 : ConversationsMessage.File.filename → name, (中文(简体) ), .url → link· ; SendTransacSms.tag 现在 string | string[]。 。 。 .
现在需要的字段数字 : GetContactDetails.whatsappBlacklisted, (中文(简体) ), Note.text, (中文(简体) ), Task.date。 。 。 .
已添加
BrevoClient接受一个新的auth自定义选项AuthProvider注射(现有)apiKey继续工作.- 新建可选字段和过滤器
contacts.createContact, (中文(简体) ),contacts.updateContact, (中文(简体) ),emailCampaigns.getEmailCampaigns, (中文(简体) ),ecommerce.getProducts,以及若干其他终点.
从 v3.x 迁移
查看迁移指南
v3.x: (中文(简体) )
import { TransactionalEmailsApi, SendSmtpEmail } from "@getbrevo/brevo";
let emailAPI = new TransactionalEmailsApi();
(emailAPI as any).authentications.apiKey.apiKey = "xkeysib-xxx";
let message = new SendSmtpEmail();
message.subject = "First email";
message.textContent = "Hello world!";
message.sender = { name: "Bob Wilson", email: "[email protected]" };
message.to = [{ email: "[email protected]", name: "Sarah Davis" }];
emailAPI.sendTransacEmail(message);
v6.x: (中文(简体) )
import { BrevoClient } from '@getbrevo/brevo';
const brevo = new BrevoClient({
apiKey: 'xkeysib-xxx',
});
await brevo.transactionalEmails.sendTransacEmail({
subject: "First email",
textContent: "Hello world!",
sender: { name: "Bob Wilson", email: "[email protected]" },
to: [{ email: "[email protected]", name: "Sarah Davis" }],
});
[尖叫声] 遗产 v3.x SDK (中文(简体) )
@getbrevo/brevo@^3.0.1将继续收到重要的安保最新情况,但没有新的特征。 我们建议迁移到v6.x.
捐款
这个图书馆是按程序创建的。 直接对图书馆作出的修改将覆盖。 请先打开一个问题讨论修改事宜 .
总是欢迎为这一研究提供捐款!