# @emailjs/browser 中文文档

规范地址：https://npmcn.com/package/%40emailjs/browser/

版本：5\.0\.3
npm 元数据更新时间：2026-10-10T15:49:30.447Z
中文译文更新时间：2026-11-13T14:29:19.135Z
软件包许可：BSD-3-Clause

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

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

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

- 包体积（解压后）：60.9 kB，80 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：0 个
- 首次发布：2021-12-29T18:44:54.941Z
- 最新版本发布：2026-10-10T15:49:30.233Z
- 近 30 天下载量：551980（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 3 个）

## 中文简介

浏览器的官方电子邮件 JS SDK

## 安装

```sh
npm install @emailjs/browser
```

也可以使用：`pnpm add @emailjs/browser`、`yarn add @emailjs/browser`、`bun add @emailjs/browser`

## README

# Web 浏览器的官方电子邮件 JS SDK

官方客户端 TypeScript 和 JavaScript SDK 为 [电子邮件JS.com](https://emailjs.com/) 顾客.

用最简单最安全的方式直接从您的代码发送邮件 .

[![codecov](https://codecov.io/gh/emailjs-com/emailjs-sdk/branch/main/graph/badge.svg?token=4I0L59Z914)](https://codecov.io/gh/emailjs-com/emailjs-sdk) [![npm version](https://img.shields.io/npm/v/@emailjs/browser.svg)](https://www.npmjs.com/package/@emailjs/browser)

-   **100%代码覆盖率 :** 此 SDK 中的每行代码、条件和错误处理器都是 完全由自动测试套件覆盖,以确保绝对生产准备和零回归问题.
-   **无外部依赖:** 搭建了零高架 尽量保持你的脚印重量.

## 目标环境通知

这个软件包是专门为网页浏览器和客户端的网页环境设计的. 如果你是在为 请使用相应的 SDK 专用平台 :

-   [节点.js](https://www.npmjs.com/package/@emailjs/nodejs)
-   [原生反应](https://www.npmjs.com/package/@emailjs/react-native)
-   [小蝶头](https://pub.dev/packages/emailjs)
-   [(原始内容存档于2013-10-12) (英语). REST API](https://www.emailjs.com/docs/rest-api/send/)

## 为什么是电子邮件JS?

### 什么是电子邮件JS?

电子邮件JS是一个 **电子邮件管弦乐层** (单位:千美元) **统一 API 中枢** 用于无缝集成 您的基础设施。 通过利用您喜欢的电子邮件服务, 从个人 Gmail 账户 和标准 SMTP 服务器给企业交易供应商,例如 SendGrid, Mailgun, resend 或 AWS SES - 电子邮件JS 集中并优化您的整个 电子邮件工作流程通过单一的,强大的界面.

### 核心建筑效益

-   **即时提供热分机:** 如果您的初级交付服务遇到停电或意外的账户阻隔,您的申请仍会在线。 通过电子邮件JS,您可以立即将您的生产流量引导到一个倒置的提供者(例如从SendGrid到AWSES),在您的仪表板中单击一击——需要 **零代码调整和零重新部署**。也可以通过不同的路径在苍蝇上动态地运行 `serviceID` 直接在您的 API 请求中 .
-   **通过"移民税":** 如果您需要更改您的电子邮件提供者, 您无需重写您的集成逻辑, 重新创建 HTML 模板, 或重映射变量 。 整合过一次电子邮件JS, 并无缝地更改基础提供者 .
-   **0 后端外页 :** 消除建立、维护和保障自定义后端服务或代理服务的必要性,以便安全地传送发送的电子邮件.
-   **普遍生态系统支助:** 任何堆叠都无缝 使用我们的官方客户端/服务器 SDKs - 或使用我们通用的 REST API 连接任何平台上的任何应用程序与 Rust, Python, PHP, C#, Go, 或任何其他语言.

## 安装和设置

### 现代 Bundlers (Vite, Next.js, Webpack, Rollup) (中文(简体) )

使用您首选的软件包管理器安装 SDK :

```bash
npm install @emailjs/browser
# yarn add @emailjs/browser
# pnpm add @emailjs/browser
# bun add @emailjs/browser
```

### 浏览器直接脚本集成( CDN)

对于没有构建步骤的应用程序,在CMS平台上运行的网站(如WordPress,Webflow, Shopify), 或香草 JavaScript 环境,直接通过 CDN 添加 SDK:

```html
<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/@emailjs/browser@5/dist/email.min.js"
></script>
```

## 代码示例

### 1\. 现代合成/等待工作流程

为React,Vue,Angular,Svelte,Next.js等组件所设计.

```typescript
import emailjs, { EmailJSResponseStatus } from '@emailjs/browser';

const templateParams = {
  name: 'James',
  notes: 'Check this out!',
};

try {
  const response = await emailjs.send('YOUR_SERVICE_ID', 'YOUR_TEMPLATE_ID', templateParams, {
    publicKey: 'YOUR_PUBLIC_KEY',
  });
  console.log('SUCCESS!', response.status, response.text);
} catch (error) {
  if (error instanceof EmailJSResponseStatus) {
    console.error('EmailJS Error:', error.status, error.text);
    return;
  }
  console.error('Unexpected Error:', error);
}
```

### 2\. 提交表格(提交表格)

自动从 HTML 窗体元素中获取输入字段,并安全地发送有效载荷.

```javascript
import emailjs from '@emailjs/browser';

emailjs
  .sendForm(
    'YOUR_SERVICE_ID',
    'YOUR_TEMPLATE_ID',
    document.querySelector('#myForm'), // Can be a direct form reference (preferred), or a string selector
    {
      publicKey: 'YOUR_PUBLIC_KEY',
    },
  )
  .then((response) => {
    console.log('SUCCESS!', response.status, response.text);
  })
  .catch((error) => {
    console.error('FAILED...', error);
  });
```

### 3\. 香草JavaScript网站整合示例

如果你正在装入 SDK 通过一个 `<script>` 标记在标准布局上.

```html
<button id="sendBtn">Send Email</button>

<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/@emailjs/browser@5/dist/email.min.js"
></script>
<script type="text/javascript">
  document.getElementById('sendBtn').addEventListener('click', function () {
    const templateParams = {
      name: 'James',
      message: 'Hello from vanilla JS!',
    };

    emailjs
      .send('YOUR_SERVICE_ID', 'YOUR_TEMPLATE_ID', templateParams, {
        publicKey: 'YOUR_PUBLIC_KEY',
      })
      .then(
        function (response) {
          console.log('SUCCESS!', response.status, response.text);
        },
        function (error) {
          console.log('FAILED...', error);
        },
      );
  });
</script>
```

## 高级配置

可在全球范围内使用 `init()` 方法或本地置换为第四个执行参数 函数`send`, (中文(简体) ), `sendForm`) (中文(简体) ). 本地选项比全球配置更为优先.

### 主要选项

| 财产 | 类型 | 默认 | 说明 |
| :-- | :-- | :-- | :-- |
| `publicKey` | `string` | —— 说 | 要求。 您的电子邮件JS账户 公证书. |
| `blockHeadless` | `boolean` | `false` | 当属实时,如果请求来自无头浏览器,则自动拒绝有错误的451执行. |
| `blockList` | `BlockList` | —— 说 | 匹配被禁值的评估和降下请求的设置 . |
| `limitRate` | `LimitRate` | —— 说 | 调和和率限制规则. |
| `storageProvider` | `StorageProvider` | —— 说 | 自定义密钥值存储引擎接口 . |

### 块列表设置

如果跟踪的变量包含或匹配被封锁的字符串,则放弃任何方法调用 。 触发时返回错误 403 .

| 财产 | 类型 | 说明 |
| :-- | :-- | :-- |
| `list` | `string[]` | 一组被禁止的字符串名词或目标值来阻挡 . |
| `watchVariable` | `string` | 要监视的有效载荷内的对象键或可变路径名. |

### 限制设置

执行请求率限制。 超过限制时返回错误 429.

| 财产 | 类型 | 默认 | 说明 |
| :-- | :-- | :-- | :-- |
| `id` | `string` | `page path` | 范围识别符号。 可以用用户、页面、组或系统自定义的ID来覆盖. |
| `throttle` | `number` | —— 说 | 连续请求之间需要的最低时间间隔(以毫秒计). |

### 自定义存储提供者接口

默认情况下, SDK 使用本地 `localStorage` 如果有的话。 您可以提供符合以下合同的自定义自动同步引擎:

```typescript
interface StorageProvider {
  get: (key: string) => Promise<string | null | undefined>;
  set: (key: string, value: string) => Promise<void>;
  remove: (key: string) => Promise<void>;
}
```

## 配置代码示例

### 设定全球安全和费率限制

```javascript
import emailjs from '@emailjs/browser';

emailjs.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  blockHeadless: true,
  blockList: {
    watchVariable: 'user_email',
    list: ['spam@malicious.com', 'bot@attack.com'],
  },
  limitRate: {
    throttle: 10000, // 10 seconds cooldown window
  },
});
```

### 本地覆盖设置

```javascript
import emailjs from '@emailjs/browser';

const payload = {
  userEmail: 'vip@example.com',
  message: 'Hello!',
};

await emailjs.send('YOUR_SERVICE_ID', 'YOUR_TEMPLATE_ID', payload, {
  publicKey: 'YOUR_PUBLIC_KEY',
  blockList: {
    watchVariable: 'userEmail', // Custom path evaluation for this request
  },
  limitRate: {
    throttle: 0, // Bypass global rate-limiting rules for this specific call
  },
});
```

## 有用链接

-   [官方 SDK 文档](https://emailjs.com/docs)
-   [电子邮件 JS 剪贴板](https://emailjs.com/)

## 常见问题

### @emailjs/browser 是什么？

浏览器的官方电子邮件 JS SDK

### 如何安装 @emailjs/browser？

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

### @emailjs/browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @emailjs/browser 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @emailjs/browser 需要什么版本的 Node\.js？

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

### @emailjs/browser 可以商用吗？

@emailjs/browser 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @emailjs/browser 的下载量有多少？

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

### @emailjs/browser 还在维护吗？

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