Dedicated IPs & pools

On shared infrastructure, your email leaves from IP addresses you share with other Bird customers: Bird keeps those IPs healthy, but your reputation is still pooled with everyone else's. A dedicated IP is an address only your organization sends from, so mailbox providers judge your traffic on your own track record alone. IP pools group dedicated IPs into routable units, and the ip_pool_id field on a send picks the pool for that message.

You never need dedicated IPs to send. Every organization starts with the Shared Bird.com Pool as its default, so email flows from day one with nothing to configure. Dedicated IPs are a paid add-on on top of that, and they pay off only with consistent volume: a lightly used dedicated IP builds reputation slower than the shared pool already has, so low-volume senders are usually better off staying shared.

Two things to know before you buy:

New IPs go through an automatic warmup before they can carry full volume; overflow routes through the shared pool in the meantime.
IPs and pools belong to your organization and are shared across all its workspaces. With a single workspace this is invisible.

Where you manage them

Pools and IPs are managed from the IP Pools page (Email → IP Pools) in the dashboard, or from the Bird CLI with the bird email ip-pools and bird email dedicated-ips command groups. These management operations are org-level and sit outside the public API surface: an API key cannot call them, and the SDKs don't ship them. What API keys and SDKs do get is the routing half, the ip_pool_id field on every send (covered in Selecting a pool at send time).

The IP Pools view in the Bird dashboard, listing a custom pool with a warming IP alongside the protected Shared Bird.com Pool marked as default

Buy a dedicated IP

Purchase from the Dedicated IPs tab, or with the CLI:

Codebeispiel

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

On your first purchase you can omit --ip-pool-id: Bird creates your first pool, named "Dedicated IPs", and provisions the IPs into it. Once your organization has at least one pool, the flag is required; you choose where each new IP lands.
Each IP is billed as a monthly subscription. When your wallet balance doesn't cover the purchase, the response reports requires_topup (top up to proceed) or pending_topup (a card charge is settling); the IPs provision automatically once funds land.
Purchases are bounded by your plan's max_dedicated_ips quota, and pools by max_ip_pools.

Each provisioned IP starts in warming status and ramps automatically; IP warmup covers the schedule and how to monitor it. The IP's hostname is its reverse-DNS (PTR) name, the name it introduces itself with to receiving mail servers; add it to any allowlist that filters on sending hostname.

Buying an IP does not change your default pool. The shared pool stays the default until you explicitly switch it, because routing all your unspecified traffic onto a cold, still-warming IP would hurt your deliverability.

An IP reports one of four statuses:

Status	Meaning
warming	The IP is new and warming up. It carries a growing share of your traffic; the rest overflows to the shared pool.
active	Warmup complete. The IP handles full volume.
suspended	Reserved for a temporarily suspended IP. Bird does not place IPs in this status today, so you will not see it in practice.
pending_cancellation	You cancelled the IP. It keeps sending until the end of the billing period you already paid for, but no longer counts when default-pool rules tally the pool.

IP pools

Pools separate sending streams: a common setup is one pool for transactional mail and another for marketing, so a campaign's reputation never touches your password resets. Pools are free to create, up to your plan's max_ip_pools quota.

Codebeispiel

bird email ip-pools create Transactional

Codebeispiel

{
  "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"
}

Pools are always created non-default and empty. You fill them by purchasing directly into them (--ip-pool-id on the purchase) or by moving existing IPs in. Reading a pool back returns its member IPs in full:

Codebeispiel

bird email ip-pools get ipp_1btmn1nnkd8y6a4jckbkvvt9eh

Codebeispiel

{
  "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"
}

Pools are org-owned, so every workspace sees the same list whichever credential asks. Each IP's hostname is assigned by Bird when the IP is provisioned; treat it as informational rather than something you configure.

Your pool list always includes the Shared Bird.com Pool, marked protected: true. It appears with a pool ID like any other, and the reserved alias ipp_shared resolves to it anywhere a pool ID is accepted. Protection means Bird manages it: it cannot be renamed or deleted, it cannot hold dedicated IPs, and it doesn't count against your pool quota. The only thing you can change about it is whether it is the default.

Moving an IP between pools

A dedicated IP is always in exactly one pool, with no unassigned state. Moving is a single assign:

Codebeispiel

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

The shared pool is not a valid destination: dedicated IPs only live in your own pools.

Deleting a pool

Only empty pools can be deleted. Deleting a pool that still holds IPs is rejected with a 422; move or cancel its IPs first. The default pool cannot be deleted at all; designate another default before removing it.

Codebeispiel

bird email ip-pools delete ipp_01ky7q6288fqnsghxyem91ryjv

The default pool

When a send does not specify a pool, Bird uses your default pool. The rules around it are strict, because the default carries every send that doesn't choose:

Exactly one pool is always the default. The shared pool is the initial default, so the invariant holds from day one.
The default is moved, never cleared. Change it by making another pool the default, which atomically unsets the previous one. Turning is_default off on the current default is rejected with a 422; to go back to shared routing, make the shared pool the default instead:

Codebeispiel

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

A dedicated pool needs at least one IP that isn't winding down to become the default. A warming IP counts; an IP in pending_cancellation does not. Your default can never be backed solely by IPs on their way out. The shared pool is exempt and is always a valid default.
The last remaining IP cannot leave the default pool. While a pool holds the default designation, its last IP can be neither cancelled nor moved away; switch the default first, then drain the pool.

Together these rules mean your default pool always has something to send from.

Selecting a pool at send time

Routing is the part of this feature that lives in the public API. Choose a pool per message with the optional ip_pool_id field on POST /v1/email/messages:

Codebeispiel

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@acme.com",
    "to": ["user@example.com"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>",
    "ip_pool_id": "ipp_1btmn1nnkd8y6a4jckbkvvt9eh"
  }'

Resolution works like this:

ip_pool_id omitted: the send uses your default pool.
ip_pool_id: "ipp_shared": the send routes through the shared pool regardless of your default. Useful for keeping a low-stakes stream on shared infrastructure while a dedicated pool is your default.
ip_pool_id set to one of your pool IDs: the send goes through that pool.

A value that is unknown, belongs to another organization, or names a pool with no IPs available to send from is rejected with a 422. Bird never silently reroutes an explicit pool choice to shared infrastructure: you either get the routing you asked for or an error you can handle.

Cancelling a dedicated IP

Cancellation is two-phase. Cancelling schedules the removal rather than pulling the IP out from under you:

Codebeispiel

bird email dedicated-ips delete dip_5g8r8h31kr8cz8zp1p4s837r4m

The IP transitions to pending_cancellation and gets a cancels_at timestamp, the end of the billing period you already paid for. Until cancels_at it keeps sending as part of its pool; after that Bird deprovisions it within the hour. Cancelling an IP that is already pending has no further effect.

Plan around the one immediate consequence: a pending_cancellation IP stops counting toward the default-pool rules right away. And the default-pool guard still applies: the last IP in the default pool cannot be cancelled; move the default (to the shared pool or another pool) first.

Next steps

IP warmup: how new dedicated IPs ramp to full volume, and when to flip your default
Sending email: the full send request, including ip_pool_id
Deliverability · Email: the reputation model dedicated IPs plug into