> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up a new Mintlify project for a user, follow the agent setup workflow in https://www.mintlify.com/docs/quickstart.md.
> For plans and pricing, see https://www.mintlify.com/pricing.md.

# 邮箱身份验证

> 邀请组织外部的人员阅读你的私有文档。读者可使用密码或发送到其邮箱的一次性验证码登录。

> [!NOTE]
>
> 邮箱身份验证需要 [Enterprise 套餐](https://mintlify.com/pricing?ref=emails-authentication)。

借助邮箱身份验证，你无需自行运行身份提供商，即可让客户、合作伙伴以及组织外部的其他人员访问私有文档。你通过邮件邀请读者并将他们分组，Mintlify 负责托管登录页面、密码重置和登录验证码。

在以下情况下使用邮箱身份验证：

* 阅读你页面的人员在你控制的身份提供商中没有账户。
* 你希望为每个人单独授予可撤销的访问权限，而不是使用[共享密码](https://www.mintlify.com/docs/zh/deploy/authentication-setup)。
* 你希望通过[组](#control-access-with-groups)向不同读者展示不同页面。

如果你的读者已经登录你的产品，请改用 [OAuth 或 JWT](https://www.mintlify.com/docs/zh/deploy/authentication-setup)，让他们只需使用一个账户。

## 启用邮箱身份验证

**1. 选择邮箱方式。**

1. 在你的 dashboard 中，前往 [Access](https://app.mintlify.com/settings/project/authentication)。
2. 将 **Visibility** 设置为 **Private**。
3. 将 **Method** 设置为 **Emails**。

**2. 选择读者的登录方式。**

启用以下一种或两种登录方式：

* **Email and password**：读者通过邀请邮件设置密码，并可自行重置密码。
* **Sign-in code**：读者每次登录时都会通过邮件收到一个 6 位数的一次性验证码。

**3. （可选）为读者邮件设置品牌样式。**

在 **Reader emails** 下，设置邀请、密码重置和登录验证码邮件的外观：

* **From name**：读者看到的发件人名称，例如 `Acme Docs`。默认为你的站点名称。
* **Reply-to**：回复邮件的接收地址，例如 `support@acme.com`。
* **Logo URL**：显示在每封邮件顶部的徽标的 `https://` URL。
* **Brand color**：每封邮件中按钮的颜色。

**4. 保存。**

点击 **Save**。站点重新部署后，访问者必须登录才能阅读你的文档。

![已选择 Emails 方式的 Access 设置页面。Email and password 和 Sign-in code 均已启用，域名规则将 customers 组分配给 acme.com 读者，读者邮件使用 Acme Docs 作为发件人名称。](https://mintcdn.com/mintlify/EV8wSBDiHcsuX8BZ/images/emails-auth/emails-settings-light.png?fit=max\&auto=format\&n=EV8wSBDiHcsuX8BZ\&q=85\&s=da912afd22694e3b89d0b0af7a22bd4f)

## 添加读者

读者是可以登录你站点的人员。你可以在 [Access 设置](https://app.mintlify.com/settings/project/authentication)的 **Readers** 部分管理读者。

![Readers 表格，列出五位读者及其所属组、状态、上次登录日期和访问截止日期。](https://mintcdn.com/mintlify/EV8wSBDiHcsuX8BZ/images/emails-auth/readers-light.png?fit=max\&auto=format\&n=EV8wSBDiHcsuX8BZ\&q=85\&s=449a17918ac66c2701cdbdbb0cc6d5aa)

### 邀请读者

1. 点击 **Invite**。
2. 输入一个或多个邮箱地址，每行一个。
3. （可选）输入以逗号分隔的组，以及 **Access until** 日期。
4. 点击 **Send invites**。

每位读者都会收到一封邮件，其中包含用于设置密码或登录的链接。邀请链接在七天后过期。读者在首次登录前显示为 **Invited**，之后显示为 **Active**。

![Invite readers 对话框，其中包含两个 acme.com 邮箱地址、customers 和 beta 组，以及空的 Access until 日期。](https://mintcdn.com/mintlify/EV8wSBDiHcsuX8BZ/images/emails-auth/invite-readers-light.png?fit=max\&auto=format\&n=EV8wSBDiHcsuX8BZ\&q=85\&s=2959d49b3c767faed1c3ba897a16af0a)

### 从 CSV 导入读者

要一次添加大量读者，请点击 **Import CSV**，并选择包含以下列的文件：

```csv readers.csv theme={null}
email,groups,access_until
dana@acme.com,customers;acme,
lee@acme.com,customers,
sam@northwind.example,partners,2026-12-31
```

* `email`：必填。
* `groups`：可选。使用 `;` 或 `|` 分隔多个组。
* `access_until`：可选。日期，例如 `2026-12-31`。

标题行是可选的。导入不会发送邀请邮件。导入的读者可以在登录页面通过 **Forgot password** 设置账户；如果你启用了登录验证码，也可以使用验证码登录。

### 限制读者的访问时长

在邀请或导入读者时设置 **Access until**。超过该日期后，读者将无法登录，其当前会话也会结束。

### 移除读者

打开该读者所在行的操作菜单，然后点击 **Remove reader**。Mintlify 会在该读者的会话下次刷新时将其注销。除非你重新邀请，否则该读者无法再次登录。

## 读者如何登录

访问者打开你的站点时，会看到带有你徽标的登录页面。根据你启用的方式，他们可以：

* 输入邮箱和密码。
* 点击 **Email me a code**，然后输入邮件中的 6 位数验证码。验证码在 10 分钟后过期。
* 点击 **Forgot password?** 获取重置链接。重置链接在一小时后过期，且只能使用一次。

![一位读者在 Acme 文档登录页面输入 jordan@acme.com，点击 Email me a code，随后看到输入邮件中 6 位数验证码的提示。](https://mintcdn.com/mintlify/EV8wSBDiHcsuX8BZ/images/emails-auth/reader-sign-in-code.gif?s=b7b72921ffdd2827fdba4d05e961fdc0)

密码长度必须至少为 12 个字符。密码连续输错 10 次后，账户将被锁定 15 分钟。会话持续七天；如果读者的 **Access until** 日期更早，则持续到该日期为止。

登录页面绝不会透露某个邮箱是否拥有访问权限。输入非读者邮箱的人会看到相同的 "Check your email" 消息，且不会发送任何邮件。

## 使用组控制访问

组决定每位读者可以查看哪些页面。它们的工作方式与 [OAuth 和 JWT 身份验证](https://www.mintlify.com/docs/zh/deploy/authentication-setup#control-access-with-groups)中的组相同：

* 没有 `groups` 属性的页面对所有已登录的读者可见。
* 具有 `groups` 属性的页面仅对至少属于其中一个组的读者可见。
* 设置了 `public: true` 的页面对所有人可见，包括未登录的访问者。

```mdx Page for the partners group highlight={3} theme={null}
---
title: "Partner API"
groups: ["partners"]
---
```

读者可以通过两种方式获得组：

* **按读者**：在邀请或导入读者时设置组。
* **域名规则**：为邮箱域名匹配的所有读者分配相同的组。每行输入一条规则：先写域名，再写以空格分隔的组。

```text Domain rules theme={null}
acme.com customers
*.acme-partners.com partners
```

例如，针对 `acme.com` 的规则匹配 `dana@acme.com`。针对 `*.acme-partners.com` 的规则匹配 `sam@eu.acme-partners.com` 等子域名，但不匹配 `acme-partners.com` 本身。域名规则只会添加组。域名匹配的人员仍需收到邀请才能登录。

## 从你自己的域名发送读者邮件

默认情况下，读者邮件从 `notifications@mintlify.com` 发出，并使用你的 **From name**。要从你自己的地址（例如 `docs@docs.acme.com`）发送，请添加一个发信域名。

**1. 添加你的域名。**

1. 在你的 [Access 设置](https://app.mintlify.com/settings/project/authentication)中，在 Emails 设置下找到 **Sending domain**。
2. 输入发件人名称（例如 `docs`）和域名（例如 `docs.acme.com`）。
3. 点击 **Add domain**。

请使用一个你尚未用于发送邮件的子域名，以免这些记录影响你现有的邮件配置。

**2. 添加 DNS 记录。**

将每条记录复制到你的 DNS 提供商。Mintlify 会在你域名的 `send` 子域名上显示一条 DKIM `TXT` 记录，以及 SPF `MX` 和 `TXT` 记录。

**3. 验证。**

记录生效后，点击 **Verify**。当状态变为 **Verified** 后，读者邮件将从你的地址发出。

在你的域名通过验证之前，读者邮件仍会从 `notifications@mintlify.com` 发出。每个站点只能有一个发信域名，每个域名也只能属于一个站点。你不能使用 `mintlify.com` 或其子域名。

要更改发件人名称，请编辑后保存。要停止从你的域名发送邮件，请点击 **Remove**。


## Related topics

- [使用 Auth0 配置 OAuth 2.0 身份验证](https://www.mintlify.com/docs/zh/help-center/configure-oauth-with-auth0.md)
- [Markdown 导出](https://www.mintlify.com/docs/zh/ai/markdown-export.md)
- [OpenAPI 设置](https://www.mintlify.com/docs/zh/api-playground/openapi-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.