专用 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。
购买专用 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 在任何接受池 ID 的地方都会解析为该池。受保护意味着由我们管理：它不能被重命名或删除，不能容纳专用 IP，也不计入你的池配额。你唯一能更改的是它是否为默认池。
在池之间移动 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默认池
当发送未指定池时，我们使用你的默认池。围绕它的规则很严格，因为默认池必须处理每一个未选择池的发送请求：
- 始终恰好有一个池是默认池。 共享池是初始默认池，因此从第一天起即满足此条件。
- 默认池只能转移，不能清除。 通过将另一个池设为默认池来更改。这会在同一时刻关闭前一个默认池的默认状态，确保每个时刻都恰好有一个默认池。对当前默认池关闭 is_default 会被拒绝并返回 422；要恢复共享路由，请改为将共享池设为默认池：
代码示例
bird email ip-pools update ipp_shared --is-default- 专用池要成为默认池，至少需要一个非退役中的 IP。warming 状态的 IP 算在内；pending_cancellation 状态的 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{
"name": "email_send",
"arguments": {
"from": {
"email": "noreply@yourdomain.com"
},
"html": "<p>Thanks for your order.</p>",
"ip_pool_id": "ipp_1btmn1nnkd8y6a4jckbkvvt9eh",
"subject": "Your receipt",
"to": [
{
"email": "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
取消分两个阶段。取消操作会安排移除，而不是立即移除 IP：
代码示例
bird email dedicated-ips delete dip_5g8r8h31kr8cz8zp1p4s837r4mIP 转为 pending_cancellation 状态并获得一个 cancels_at 时间戳，即你已付费的计费周期结束时间。在 cancels_at 之前，它继续作为池的一部分发送邮件；之后我们会在一小时内取消配置。对已处于待取消状态的 IP 再次取消不会产生额外效果。
请注意一个即时后果：pending_cancellation 状态的 IP 会立即停止计入默认池规则。默认池保护机制仍然适用：默认池中的最后一个 IP 不能被取消；请先将默认池转移（到共享池或另一个池）。
后续步骤
- IP 预热：新专用 IP 如何逐步提升到全部流量，以及何时切换默认池
- 发送邮件：完整的发送请求，包括 ip_pool_id
- 投递率 · 邮件：专用 IP 所接入的信誉模型
- 购买专用 IP：在控制台中购买专用 IP 并展示预热启动过程的视频