---
title: "Create an IP pool"
method: POST
path: "/email/ip_pools"
tags: ["IP Pools"]
---

# Create an IP pool

`POST /email/ip_pools`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/email/ip_pools`
- Auth: HTTP bearer

Create an account-scoped pool of dedicated IPs. Set `is_default` or `domain_id` for the pool to carry mail; a pool with neither carries none.

## Request body

- IpPoolCreateRequest
  - `name` string, required: Pool name: 1-64 characters of lowercase letters, digits, `.`, `_`, and `-`, starting and ending with a letter or digit. Must be unique within the account and must not start with `dip_`.
  - `is_default` boolean: Make this the account's default pool, which carries mail for sending domains without a domain-scoped pool. An account can have one default pool. Defaults to `false`.
  - `domain_id` string, uuid: Scope the pool to one of the account's email domains; the pool then carries that domain's mail. Scope at most one pool to each domain.

## Response `201`

Created IP pool

- IpPoolShowResponse
  - `data` IpPool, required: An account-scoped pool of dedicated IPs. Mail uses a pool only when the pool is scoped to the sending domain (`domain_id`) or is the account default (`is_default`).
    - `id` string, uuid
    - `record_type` 'ip_pool'
    - `name` string: Pool name, unique within the account.
    - `is_default` boolean: Whether this is the account's default pool. The default pool carries mail for sending domains that have no domain-scoped pool. At most one per account.
    - `domain_id` string, uuid, nullable: Email domain this pool is scoped to. The pool carries that domain's mail. Null when the pool is not domain-scoped.
    - `ips` IpPoolMemberIp[]: Member IPs with their routing weights. Populated by Retrieve an IP pool; list, create, and update responses return an empty array.
      - `id` string, uuid
      - `record_type` 'dedicated_ip'
      - `ip_address` string: The allocated IPv4/IPv6 address.
      - `ip_version` 'ipv4' | 'ipv6'
      - `pool_id` string, uuid, nullable
      - `region` string: Region label of the allocated IP (for example, `ewr-nj1`).
      - `status` 'provisioning' | 'warming_up' | 'active' | 'suspended' | 'released': Lifecycle status. `provisioning`: purchased and billed, carries no mail until `start_warmup`. `warming_up`: warm-up ramp in progress. `active`: ramp complete. `suspended`: suspended by Telnyx; carries no mail and is still billed. `released`: returned to Telnyx; carries no mail.
      - `warmup` DedicatedIpWarmup: Warmup ramp state for a dedicated IP.
        - `started_at` string, date-time, nullable: When `start_warmup` was called. Null before warm-up starts and after release.
        - `progress` integer: Ramp progress (0-100): the share of the 28 send-day schedule completed. Only UTC days on which the IP sent mail count. Set to 100 when the ramp completes, automatically or through `complete_warmup`. On an `active` IP this value is informational and can keep an earlier value after a suspension is lifted.
        - `daily_cap` integer, nullable: Daily cap of the current ramp stage. Null until the scheduler arms the first stage, and cleared when the ramp completes, automatically or through `complete_warmup`. On an `active` IP this value is informational and can keep an earlier stage cap after a suspension is lifted; it does not limit sending.
        - `paused` boolean: True while the ramp is paused.
        - `paused_at` string, date-time, nullable: When the ramp was paused. Null when not paused.
        - `today` object, nullable: Today's warmup allowance report card (current UTC day). Null outside the warmup window (before start_warmup, after release/suspension). `active` IPs report the ramp-complete allowance, except as described for `cap`.
          - `day` string, date: The UTC day this snapshot describes (warmup caps reset at UTC midnight).
          - `cap` integer, nullable: The day's allowance cap. Null when the ramp has not opened yet (day 0: the scheduler has not armed a stage cap) — distinct from a spent day, which reports the cap with remaining 0. `active` IPs report `100000000`, the ramp-complete cap; `complete_warmup` applies it to the current day immediately. A day's allowance created before the IP became `active` can keep its stored `cap` and `remaining` until the next first-attempt send refreshes them.
          - `granted` integer: First-attempt sends released from warmup hold so far today. Delivery retries never lease allowance and are not counted.
          - `remaining` integer, nullable: Headroom left today. A queued send held by the daily cap is explained by remaining == 0; null mirrors cap (ramp not open yet). On an `active` IP whose `cap` is below `100000000`, remaining == 0 is a stored allowance and does not block the next eligible first-attempt send.
      - `billing` DedicatedIpBilling: Monthly recurring charge (MRC) state for the IP's current allocation.
        - `status` 'not_started' | 'pending' | 'in_progress' | 'active' | 'stopping' | 'stopped' | 'stop_failed' | 'failed': `not_started`: no charge recorded for the current allocation. `pending`: the charge is queued. `in_progress`: the charge is being created. `active`: the MRC is active. `stopping`: release requested; the MRC stop is being processed. `stopped`: the MRC has stopped. `stop_failed`: the MRC stop failed and the charge remains. `failed`: the charge could not be created.
        - `charged` boolean: True when `status` is `active`, `stopping`, or `stop_failed`. An IP carries mail only after its charge has been created.
      - `provisioning_status` 'not_applicable' | 'pending_ptr' | 'pending_dns' | 'dns_confirmed' | 'dns_lost': Same value as `provisioning.dns_status`.
      - `provisioning` DedicatedIpProvisioning: Read-only status of the Telnyx-managed PTR record. No customer action is required to complete it.
        - `dns_status` 'not_applicable' | 'pending_ptr' | 'pending_dns' | 'dns_confirmed' | 'dns_lost': `dns_confirmed`: the PTR is forward-confirmed and `dns_confirmed_at` is set. `pending_ptr`: the PTR record is not yet in place. `pending_dns`: the PTR record is waiting for forward confirmation. `dns_lost`: a previously confirmed PTR no longer confirms, or the PTR request was abandoned before it ever confirmed (`ptr_request_state` is `abandoned`); the IP carries no mail until DNS is confirmed. `not_applicable`: the IP is released or has no PTR record on file.
        - `ptr_request_state` 'pending' | 'pr_open' | 'merged' | 'confirmed' | 'failed' | 'abandoned' | 'null', nullable: State of the Telnyx PTR change: `pending`, `pr_open`, `merged`, `confirmed`, `failed`, or `abandoned`. Informational.
        - `ptr_request_pr_url` string, nullable: Reference to the Telnyx PTR change request, when one exists. Informational.
        - `checklist` object: Informational progress flags for the Telnyx-managed PTR. They do not gate `start_warmup`; use `dns_status` to check whether the IP can carry mail.
          - `ptr_requested` boolean
          - `ptr_authored` boolean
          - `ptr_merged` boolean
          - `forward_confirmed` boolean
      - `ptr_hostname` string, nullable: Telnyx-managed reverse DNS (PTR) hostname of the IP, in the form `mta-<a-b-c-d>.msgtelnyx.com`. Also used as the EHLO hostname when sending from the IP. Managed by Telnyx and cannot be changed through the API.
      - `dns_confirmed_at` string, date-time, nullable: When the PTR hostname was forward-confirmed (PTR → hostname → A record → this IP). The IP carries mail only while this is set.
      - `quarantine_until` string, date-time, nullable: Set on release to 30 days after `released_at`. The address is not returned to stock before this time.
      - `released_at` string, date-time, nullable: When the IP was released. Null until release.
      - `suspension_reason` string, nullable: Reason Telnyx recorded when suspending the IP. Null unless `status` is `suspended`.
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400`: Malformed request
- `401`: Unauthorized
- `404`: The referenced email domain was not found.
- `422`: Validation failed: invalid or duplicate `name`, a second default pool, or a `domain_id` owned by another account.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-22** `8b7c33b1ee45`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/email/ip_pools/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)