专用 IP 与 IP 池

在共享基础设施上，你的邮件从与其他客户共用的 IP 地址发出。我们会维护这些 IP 的健康状态，但你的信誉仍然与其他人共享。专用 IP 是仅供你的组织发送的地址，邮箱提供商会仅根据你自己的发送记录来评估你的流量。IP 池将专用 IP 分组为可路由的单元，发送时通过 ip_pool_id 字段选择该消息使用的池。

发送邮件不需要专用 IP。每个组织默认使用 Shared Bird.com Pool，因此从第一天起无需任何配置即可发送邮件。专用 IP 是付费附加功能，只有在发送量稳定时才值得投入。使用量低的专用 IP 积累信誉的速度比共享池已有的信誉更慢，因此低流量发送者通常更适合留在共享池。专用 IP 能否提升邮件投递率？介绍了发送量和信誉如何影响这一选择。

购买之前需要了解两件事：

新 IP 在能够承载全部流量之前会经历自动预热；期间超出部分通过共享池路由。
IP 和池归属于你的组织。

管理位置

在控制台的 Email > IP pools 中管理池和 IP，或使用 bird email ip-pools 和 bird email dedicated-ips CLI 命令。这些操作需要组织级权限。SDK 不包含类型化的管理方法。要通过池路由消息，请按发送时选择池中的说明设置 ip_pool_id。

如果你的组织按工作区管理池访问权限，组织的 Email > IP pools 页面会显示组织的 IP 清单和工作区分配情况。工作区页面显示该工作区可以使用的池。更改这些分配需要组织权限；拥有某个工作区的访问权限并不能访问其同级工作区的池。

控制台中的 IP Pools 视图，列出一个包含预热中 IP 的自定义池以及标记为默认的受保护 Shared Bird.com Pool

购买专用 IP

从 Dedicated IPs 选项卡或使用 CLI 购买 IP：

代码示例

bird email dedicated-ips create --quantity 1 --ip-pool-id ipp_1btmn1nnkd8y6a4jckbkvvt9eh

首次购买时可以省略 --ip-pool-id：我们会创建你的第一个池，命名为 "Dedicated IPs"，并将 IP 分配到其中。一旦你的组织拥有至少一个池，该标志就变为必填；你可以选择每个新 IP 的去处。
每个 IP 按月订阅计费。当钱包余额不足以支付购买时，响应会返回 requires_topup（需要充值后继续）或 pending_topup（银行卡扣款正在处理中）；资金到账后 IP 会自动配置。
购买数量受你套餐的 email_ip_dedicated_max 配额限制，池数量受 email_ip_pools_max 限制。

每个已配置的 IP 初始状态为 warming，并自动逐步提升流量；IP 预热介绍了计划和监控方式。IP 的 hostname 是它的反向 DNS（PTR）名称，即它向收件邮件服务器自我介绍时使用的主机名；将其添加到任何根据发送主机名过滤的白名单中。

购买 IP 不会更改你的默认池。共享池会一直保持为默认池，直到你明确切换，因为将所有未指定池的流量路由到一个冷的、仍在预热中的 IP 会损害你的投递率。

IP 会报告以下四种状态之一：

状态	含义
`warming`	IP 是新的，正在预热中。它承担你流量中逐渐增长的份额；其余部分溢出到共享池。
`active`	预热完成。该 IP 可承载全部流量。
`suspended`	该 IP 被临时暂停。
`pending_cancellation`	你已取消该 IP。它会继续发送直到你已付费的计费周期结束，但在默认池规则统计池成员时不再计入。

IP 池

池用于分隔发送流：常见的做法是一个池用于事务性邮件，另一个用于营销邮件，这样营销活动的信誉不会影响你的密码重置邮件。池可免费创建，数量上限为你套餐的 email_ip_pools_max 配额。

代码示例

bird email ip-pools create Transactional

代码示例

{
  "created_at": "2026-07-23T14:48:28Z",
  "id": "ipp_01ky7q6288fqnsghxyem91ryjv",
  "ips": [],
  "is_default": false,
  "name": "Transactional",
  "organization_id": "org_01ky7m21hjffg9pxj5xz6nx6ew",
  "protected": false,
  "updated_at": "2026-07-23T14:48:28Z"
}

池创建时始终为非默认且为空。你可以通过在购买时直接将 IP 分配到池中（购买时使用 --ip-pool-id）或移入已有的 IP 来填充它们。读取池信息时会完整返回其成员 IP：

代码示例

bird email ip-pools get ipp_1btmn1nnkd8y6a4jckbkvvt9eh

代码示例

{
  "created_at": "2026-06-29T13:56:39Z",
  "id": "ipp_1btmn1nnkd8y6a4jckbkvvt9eh",
  "ips": [
    {
      "address": "198.51.100.21",
      "created_at": "2026-06-29T13:56:39Z",
      "hostname": "mta1.send.goldcrest.dev",
      "id": "dip_5g8r8h31kr8cz8zp1p4s837r4m",
      "ip_pool_id": "ipp_1btmn1nnkd8y6a4jckbkvvt9eh",
      "organization_id": "org_01ky7m235keybaf72b0fdgfwj4",
      "purchased_at": "2026-06-29T13:56:39Z",
      "status": "active",
      "updated_at": "2026-07-23T13:56:39Z",
      "warmup_completed_at": "2026-07-15T13:56:39Z",
      "warmup_progress": 100,
      "warmup_started_at": "2026-06-29T13:56:39Z"
    }
  ],
  "is_default": false,
  "name": "Goldcrest Pool",
  "organization_id": "org_01ky7m235keybaf72b0fdgfwj4",
  "protected": false,
  "updated_at": "2026-07-23T13:56:39Z"
}

池归组织所有。每个 IP 的 hostname 在配置时自动分配；将其视为信息性字段，而非需要手动配置的内容。

组织的池清单包含 Shared Bird.com Pool，标记为 protected: true。它拥有池 ID，保留别名 ipp_shared 会解析为该池。它由 Bird 管理：不能重命名或删除，不能容纳专用 IP，也不计入你的池配额。已分配池的工作区只有在共享池被分配给该工作区时才能看到它。使用该别名所需的权限与使用其 ID 相同。

工作区分配功能可用时，控制台会授予当前工作区使用新建池的权限。在控制台首次购买专用 IP 时，请先创建池，再确认付款。通过 API 或 CLI 购买时，如果未提供池 ID，系统会创建一个组织级池，该池仍需分配给工作区。

在支持工作区分配时，可以授予某个池的使用权而不更改工作区的默认池：

代码示例

bird email ip-pools workspaces assign ipp_1btmn1nnkd8y6a4jckbkvvt9eh ws_01krdgeqcxet5s7t44vh8rt9mg --is-default=false

对于没有任何分配的工作区，此操作还会将共享池分配为其默认池，从而保留共享发送。如果省略 --is-default 或将其设为 true，则会改为将第一个分配的池设为默认池，并将发送限制在已分配的池中。预热中的专用池还需要分配共享池，因为预热期间的溢出流量使用共享 IP。没有池分配的工作区使用共享池。

要移除分配，请先替换所有默认选择，以及域名默认设置、邮箱、SMTP 设置或草稿、已计划、未完成的群发中保存的使用。已完成的群发历史会保留其原始池标识，不会阻止移除。

代码示例

bird email ip-pools workspaces remove ipp_1btmn1nnkd8y6a4jckbkvvt9eh ws_01krdgeqcxet5s7t44vh8rt9mg --yes

在池之间移动 IP

专用 IP 始终恰好在一个池中，不存在未分配的状态。移动即一次分配操作：

代码示例

bird email dedicated-ips assign dip_5g8r8h31kr8cz8zp1p4s837r4m --ip-pool-id ipp_01ky7q6288fqnsghxyem91ryjv

共享池不是有效的目标：专用 IP 只能存在于你自己的池中。

删除池

只有空池才能删除。删除仍包含 IP 的池会被拒绝并返回 409；请先移走或取消其中的 IP。删除池之前，请替换其默认选择，并移除其工作区分配和保存的使用。

代码示例

bird email ip-pools delete ipp_01ky7q6288fqnsghxyem91ryjv --yes

默认池

当发送请求及其发件域名都未选择池时，我们使用你的默认池。对于按工作区管理池的组织，这就是工作区的默认池。以下规则适用于该默认池：

始终恰好有一个池是默认池。 共享池是初始默认池，因此从第一天起即满足此条件。
默认池只能转移，不能清除。 通过将另一个池设为默认池来更改。这会在同一时刻关闭前一个默认池的默认状态，确保每个时刻都恰好有一个默认池。对当前默认池关闭 is_default 会被拒绝并返回 422；要恢复共享路由，请改为将共享池设为默认池：

代码示例

bird email ip-pools update ipp_shared --is-default

对于按工作区管理池的组织，请改为选择工作区的默认池：

代码示例

bird email ip-pools workspaces assign ipp_shared ws_01krdgeqcxet5s7t44vh8rt9mg --is-default

当组织级 update --is-default 操作返回 IPPoolOrganizationDefaultRetired 时，请使用工作区分配。过渡期间，分配更改可能暂时不可用。更改一个工作区的默认池不会影响其他工作区的默认池。

专用池要成为默认池，至少需要一个非退役中的 IP。warming 状态的 IP 算在内；pending_cancellation 状态的 IP 不算。你的默认池永远不能仅由即将退出的 IP 支撑。共享池不受此限制，始终是有效的默认池。
最后一个 IP 不能离开默认池。 当池持有默认标识时，其最后一个 IP 既不能取消也不能移走；请先切换默认池，然后再清空该池。

这些检查保护的是计划内的更改。如果专用池失去其发送 IP 或所需权限，通过该池的发送会失败，直到你恢复该池或选择另一个有权限的默认池。

发送时选择池

路由是此功能中位于公共 API 中的部分。通过 POST /v1/email/messages 上的可选 ip_pool_id 字段为每条消息选择池：

await bird.email.send({
  from: "noreply@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your receipt",
  html: "<p>Thanks for your order.</p>",
  ip_pool_id: "ipp_1btmn1nnkd8y6a4jckbkvvt9eh",
});

client.email.send(
    from_="noreply@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Your receipt",
    html="<p>Thanks for your order.</p>",
    ip_pool_id="ipp_1btmn1nnkd8y6a4jckbkvvt9eh",
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:     "noreply@yourdomain.com",
	To:       []string{"delivered@messagebird.dev"},
	Subject:  "Your receipt",
	HTML:     "<p>Thanks for your order.</p>",
	IpPoolId: "ipp_1btmn1nnkd8y6a4jckbkvvt9eh",
})

$bird->email->send(
    from: 'noreply@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Your receipt',
    html: '<p>Thanks for your order.</p>',
    ipPoolId: 'ipp_1btmn1nnkd8y6a4jckbkvvt9eh',
);

bird email send \
  --from noreply@yourdomain.com \
  --html '<p>Thanks for your order.</p>' \
  --ip-pool-id ipp_1btmn1nnkd8y6a4jckbkvvt9eh \
  --subject 'Your receipt' \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>",
    "ip_pool_id": "ipp_1btmn1nnkd8y6a4jckbkvvt9eh"
  }'

解析逻辑如下：

省略 ip_pool_id：如果当前工作区中为发件域名设置了默认池，发送将使用该池；否则，使用你的默认路由。
ip_pool_id: "ipp_shared"：当你的工作区可以使用共享池时，发送使用共享池。即使专用池是你的默认池，此设置也会选择共享基础设施。
ip_pool_id 设为某个池 ID：当该池可供你的工作区使用时，发送使用该池。

如果值无法识别、对该工作区不可用，或指向没有可用 IP 的池，请求会被拒绝并返回 422。包含预热中 IP 的专用池还需要使用共享池的权限，因为预热溢出流量要经过共享池。移除共享池权限后，该预热路由将不可用。对于已接受的消息，系统会保留明确的池选择，并在发送前再次检查；之后移除权限可能导致投递停止。Bird 不会用其他池替换不可用的明确选择。

取消专用 IP

取消分两个阶段。取消操作会安排移除，而不是立即移除 IP：

代码示例

bird email dedicated-ips delete dip_5g8r8h31kr8cz8zp1p4s837r4m --yes

IP 转为 pending_cancellation 状态并获得一个 cancels_at 时间戳，即你已付费的计费周期结束时间。在 cancels_at 之前，它继续作为池的一部分发送邮件；之后我们会在一小时内取消配置。对已处于待取消状态的 IP 再次取消不会产生额外效果。

请注意一个即时后果：pending_cancellation 状态的 IP 会立即停止计入默认池规则。默认池保护机制仍然适用：默认池中的最后一个 IP 不能被取消；请先将默认池转移（到共享池或另一个池）。

后续步骤

IP 预热：新专用 IP 如何逐步提升到全部流量，以及何时切换默认池
发送邮件：完整的发送请求，包括 ip_pool_id
投递率 · 邮件：专用 IP 所接入的信誉模型
购买专用 IP：在控制台中购买专用 IP 并展示预热启动过程的视频

继续查看此主题的文档、指南和示例。

获取实施简报

相关资源