# @emailit/node 中文文档

规范地址：https://npmcn.com/package/%40emailit/node/

版本：2\.0\.4
npm 元数据更新时间：2026-03-05T11:17:09.426Z
中文译文更新时间：2026-11-14T06:58:20.323Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40emailit/node
原文对照：https://npmcn.com/package/%40emailit/node/?lang=original
项目主页：https://emailit.com/
源码仓库：https://github.com/emailit/emailit-node

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：102 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-03-05T10:03:39.150Z
- 最新版本发布：2026-03-05T11:17:09.066Z
- 近 30 天下载量：2188（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

电子邮件电子邮件 API 的节点.js SDK

## 安装

```sh
npm install @emailit/node
```

也可以使用：`pnpm add @emailit/node`、`yarn add @emailit/node`、`bun add @emailit/node`

## README

# 电子邮件节点.js

[![Tests](https://img.shields.io/github/actions/workflow/status/emailit/emailit-node/tests.yml?label=tests&style=for-the-badge&labelColor=111827)](https://github.com/emailit/emailit-node/actions) [![npm Version](https://img.shields.io/npm/v/@emailit/node?style=for-the-badge&labelColor=111827)](https://www.npmjs.com/package/@emailit/node) [![License](https://img.shields.io/github/license/emailit/emailit-node?style=for-the-badge&labelColor=111827)](https://github.com/emailit/emailit-node/blob/main/LICENSE)

官方节点Js SDK [电子邮件](https://emailit.com/) 电子邮件API.

## 所需资源

-   节点.js 18+

## 安装

```bash
npm install @emailit/node
```

## 开始

```js
import { Emailit } from '@emailit/node';

const emailit = new Emailit('your_api_key');

const email = await emailit.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Hello from Emailit',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
});

console.log(email.id);     // em_abc123...
console.log(email.status); // pending
```

所有服务方法都返回有直接属性访问的资源对象——就像"Frede SDK"一样.

## 可用服务

| 服务 | 财产 | 说明 |
| --- | --- | --- |
| 电子邮件 | `emailit.emails` | 发送、列表、获取、取消、重试电子邮件 |
| 域数 | `emailit.domains` | 创建、核实、列表、管理发送域 |
| API 密钥 | `emailit.apiKeys` | 创建、列表、管理 API 密钥 |
| 观众 | `emailit.audiences` | 创建、列表、管理受众 |
| 订阅者 | `emailit.subscribers` | 添加、 列表、 在受众中管理订阅者 |
| 模板 | `emailit.templates` | 创建、 列出、 发布电子邮件模板 |
| 抑制 | `emailit.suppressions` | 创建、 列表、 管理被压制的地址 |
| 电子邮件验证 | `emailit.emailVerifications` | 校验电子邮件地址 |
| 电子邮件核查清单 | `emailit.emailVerificationLists` | 创建、 列出、 获取结果、 导出 |
| 网络呼号 | `emailit.webhooks` | 创建、列表、管理webhooks |
| 联系人 | `emailit.contacts` | 创建、列表、管理联系人 |
| 活动 | `emailit.events` | 列出和检索事件 |

## 使用量

### 电子邮件

#### 发送电子邮件

```js
const email = await emailit.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Hello from Emailit',
  html: '<h1>Welcome!</h1>',
});

console.log(email.id);
console.log(email.status);
```

#### 以模板发送

```js
const email = await emailit.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  template: 'welcome_email',
  variables: {
    name: 'John Doe',
    company: 'Acme Inc',
  },
});
```

#### 随附件一起发送

```js
import { readFileSync } from 'node:fs';

const email = await emailit.emails.send({
  from: 'invoices@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Your Invoice #12345',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: readFileSync('invoice.pdf').toString('base64'),
      content_type: 'application/pdf',
    },
  ],
});
```

#### 计划电子邮件

```js
const email = await emailit.emails.send({
  from: 'reminders@yourdomain.com',
  to: 'user@example.com',
  subject: 'Appointment Reminder',
  html: '<p>Your appointment is tomorrow at 2 PM.</p>',
  scheduled_at: '2026-01-10T09:00:00Z',
});

console.log(email.status);       // scheduled
console.log(email.scheduled_at); // 2026-01-10T09:00:00Z
```

#### 列出电子邮件

```js
const emails = await emailit.emails.list({ page: 1, limit: 10 });

for (const email of emails) {
  console.log(`${email.id} — ${email.status}`);
}

if (emails.hasMore()) {
  // fetch next page
}
```

#### 取消/ 重试

```js
await emailit.emails.cancel('em_abc123');
await emailit.emails.retry('em_abc123');
```

* * *

### 域数

```js
// Create a domain
const domain = await emailit.domains.create({
  name: 'example.com',
  track_loads: true,
  track_clicks: true,
});
console.log(domain.id);

// Verify DNS
const verified = await emailit.domains.verify('sd_123');

// List all domains
const domains = await emailit.domains.list();

// Get a domain
const d = await emailit.domains.get('sd_123');

// Update a domain
await emailit.domains.update('sd_123', { track_clicks: false });

// Delete a domain
await emailit.domains.delete('sd_123');
```

* * *

### API 密钥

```js
// Create an API key
const key = await emailit.apiKeys.create({
  name: 'Production Key',
  scope: 'full',
});
console.log(key.key); // only available on create

// List all API keys
const keys = await emailit.apiKeys.list();

// Get an API key
const k = await emailit.apiKeys.get('ak_123');

// Update an API key
await emailit.apiKeys.update('ak_123', { name: 'Renamed Key' });

// Delete an API key
await emailit.apiKeys.delete('ak_123');
```

* * *

### 观众

```js
// Create an audience
const audience = await emailit.audiences.create({ name: 'Newsletter' });
console.log(audience.id);
console.log(audience.token);

// List audiences
const audiences = await emailit.audiences.list();

// Get an audience
const a = await emailit.audiences.get('aud_123');

// Update an audience
await emailit.audiences.update('aud_123', { name: 'Updated Newsletter' });

// Delete an audience
await emailit.audiences.delete('aud_123');
```

* * *

### 订阅者

订阅者属于一个受众,因此观众ID总是第一个论据.

```js
// Add a subscriber
const subscriber = await emailit.subscribers.create('aud_123', {
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe',
});

// List subscribers in an audience
const subscribers = await emailit.subscribers.list('aud_123');

// Get a subscriber
const s = await emailit.subscribers.get('aud_123', 'sub_456');

// Update a subscriber
await emailit.subscribers.update('aud_123', 'sub_456', {
  first_name: 'Jane',
});

// Delete a subscriber
await emailit.subscribers.delete('aud_123', 'sub_456');
```

* * *

### 模板

```js
// Create a template
const template = await emailit.templates.create({
  name: 'Welcome',
  subject: 'Welcome!',
  html: '<h1>Hi {{name}}</h1>',
});

// List templates
const templates = await emailit.templates.list();

// Get a template
const t = await emailit.templates.get('tem_123');

// Update a template
await emailit.templates.update('tem_123', { subject: 'New Subject' });

// Publish a template
await emailit.templates.publish('tem_123');

// Delete a template
await emailit.templates.delete('tem_123');
```

* * *

### 抑制

```js
// Create a suppression
const suppression = await emailit.suppressions.create({
  email: 'spam@example.com',
  type: 'hard_bounce',
  reason: 'Manual suppression',
});

// List suppressions
const suppressions = await emailit.suppressions.list();

// Get a suppression
const sup = await emailit.suppressions.get('sup_123');

// Update a suppression
await emailit.suppressions.update('sup_123', { reason: 'Updated' });

// Delete a suppression
await emailit.suppressions.delete('sup_123');
```

* * *

### 电子邮件验证

```js
const result = await emailit.emailVerifications.verify({
  email: 'test@example.com',
});

console.log(result.status); // valid
console.log(result.score);  // 0.95
console.log(result.risk);   // low
```

* * *

### 电子邮件核查清单

```js
// Create a verification list
const list = await emailit.emailVerificationLists.create({
  name: 'Marketing List Q1',
  emails: [
    'user1@example.com',
    'user2@example.com',
    'user3@example.com',
  ],
});
console.log(list.id);     // evl_abc123...
console.log(list.status); // pending

// List all verification lists
const lists = await emailit.emailVerificationLists.list();

// Get a verification list
const vl = await emailit.emailVerificationLists.get('evl_abc123');
console.log(vl.stats.successful_verifications);

// Get verification results
const results = await emailit.emailVerificationLists.results('evl_abc123', { page: 1, limit: 50 });

for (const r of results) {
  console.log(`${r.email} — ${r.result}`);
}

// Export results as XLSX
import { writeFileSync } from 'node:fs';
const response = await emailit.emailVerificationLists.export('evl_abc123');
writeFileSync('results.xlsx', response.body);
```

* * *

### 网络呼号

```js
// Create a webhook
const webhook = await emailit.webhooks.create({
  name: 'My Webhook',
  url: 'https://example.com/hook',
  all_events: true,
  enabled: true,
});
console.log(webhook.id);

// List webhooks
const webhooks = await emailit.webhooks.list();

// Get a webhook
const wh = await emailit.webhooks.get('wh_123');

// Update a webhook
await emailit.webhooks.update('wh_123', { enabled: false });

// Delete a webhook
await emailit.webhooks.delete('wh_123');
```

* * *

### 联系人

```js
// Create a contact
const contact = await emailit.contacts.create({
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe',
});
console.log(contact.id);

// List contacts
const contacts = await emailit.contacts.list();

// Get a contact
const c = await emailit.contacts.get('con_123');

// Update a contact
await emailit.contacts.update('con_123', { first_name: 'Jane' });

// Delete a contact
await emailit.contacts.delete('con_123');
```

* * *

### 活动

```js
// List events
const events = await emailit.events.list({ type: 'email.delivered' });

for (const event of events) {
  console.log(event.type);
}

// Get an event
const event = await emailit.events.get('evt_123');
console.log(event.type);
console.log(event.data.email_id);
```

## Webhook 事件

SDK为事件模块下的所有 Emailit Webhook 事件类型提供打入的事件类,外加 a `WebhookSignature` 用于验证 webhook 请求签名的类.

### 正在验证 Webhook 签名

```js
import { WebhookSignature, EmailDelivered } from '@emailit/node';

const rawBody = await request.text();
const signature = request.headers.get('x-emailit-signature');
const timestamp = request.headers.get('x-emailit-timestamp');
const secret = 'your_webhook_signing_secret';

try {
  const event = WebhookSignature.verify(rawBody, signature, timestamp, secret);

  // event is automatically typed based on the event type
  console.log(event.type);     // e.g. "email.delivered"
  console.log(event.event_id); // e.g. "evt_abc123"

  // Access the event data
  const data = event.getEventData();

  if (event instanceof EmailDelivered) {
    // Handle delivered email
  }
} catch (e) {
  // Invalid signature or timestamp
  return new Response(e.message, { status: 401 });
}
```

您可以通过路过来禁用重放保护 `null` 容忍,或以秒计设定习惯容忍:

```js
// Skip replay check
const event = WebhookSignature.verify(rawBody, signature, timestamp, secret, null);

// Custom 10-minute tolerance
const event = WebhookSignature.verify(rawBody, signature, timestamp, secret, 600);
```

### 可用事件类型

**电子邮件 :** `email.accepted`, (中文(简体) ), `email.scheduled`, (中文(简体) ), `email.delivered`, (中文(简体) ), `email.bounced`, (中文(简体) ), `email.attempted`, (中文(简体) ), `email.failed`, (中文(简体) ), `email.rejected`, (中文(简体) ), `email.suppressed`, (中文(简体) ), `email.received`, (中文(简体) ), `email.complained`, (中文(简体) ), `email.clicked`, (中文(简体) ), `email.loaded`

**域数 :** `domain.created`, (中文(简体) ), `domain.updated`, (中文(简体) ), `domain.deleted`

**观众:** `audience.created`, (中文(简体) ), `audience.updated`, (中文(简体) ), `audience.deleted`

**订阅者 :** `subscriber.created`, (中文(简体) ), `subscriber.updated`, (中文(简体) ), `subscriber.deleted`

**联系人 :** `contact.created`, (中文(简体) ), `contact.updated`, (中文(简体) ), `contact.deleted`

**模板 :** `template.created`, (中文(简体) ), `template.updated`, (中文(简体) ), `template.deleted`

**抑制:** `suppression.created`, (中文(简体) ), `suppression.updated`, (中文(简体) ), `suppression.deleted`

**电子邮件验证 :** `email_verification.created`, (中文(简体) ), `email_verification.updated`, (中文(简体) ), `email_verification.deleted`

**电子邮件核查清单:** `email_verification_list.created`, (中文(简体) ), `email_verification_list.updated`, (中文(简体) ), `email_verification_list.deleted`

每个事件类型都有相应的类(例如. `EmailDelivered`, (中文(简体) ), `DomainCreated`) (中文(简体) ). 你用得着 `instanceof` 检查或检查 `EVENT_TYPE` 用于路由的静态属性 :

```js
import { EmailDelivered, EmailBounced, ContactCreated } from '@emailit/node';

if (event instanceof EmailDelivered) {
  handleDelivered(event);
} else if (event instanceof EmailBounced) {
  handleBounce(event);
} else if (event instanceof ContactCreated) {
  handleNewContact(event);
}
```

## 处理错误

SDK 投放 API 错误的打出例外 :

```js
import {
  AuthenticationException,
  InvalidRequestException,
  RateLimitException,
  UnprocessableEntityException,
  ApiConnectionException,
  ApiErrorException,
} from '@emailit/node';

try {
  await emailit.emails.send({ /* ... */ });
} catch (e) {
  if (e instanceof AuthenticationException) {
    // Invalid API key (401)
  } else if (e instanceof InvalidRequestException) {
    // Bad request or not found (400, 404)
  } else if (e instanceof RateLimitException) {
    // Too many requests (429)
  } else if (e instanceof UnprocessableEntityException) {
    // Validation failed (422)
  } else if (e instanceof ApiConnectionException) {
    // Network error
  } else if (e instanceof ApiErrorException) {
    // Any other API error
    console.log(e.httpStatus);
    console.log(e.httpBody);
    console.log(e.jsonBody);
  }
}
```

## 许可证

麻省理工学院 -- -- 见 [自由主义](https://npmcn.com/package/%40emailit/node/LICENSE) 详细情况.

## 常见问题

### @emailit/node 是什么？

电子邮件电子邮件 API 的节点\.js SDK

### 如何安装 @emailit/node？

在项目目录运行 npm install @emailit/node，或使用 pnpm add / yarn add / bun add。

### @emailit/node 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/emailit\_\_node 是否存在。

### @emailit/node 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @emailit/node 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @emailit/node 可以商用吗？

@emailit/node 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @emailit/node 的下载量有多少？

根据 npm 官方下载统计，@emailit/node 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,188 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @emailit/node 还在维护吗？

最新版本 2\.0\.4 发布于 2026/03/05（8 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/03/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。