> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an IP pool > 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. ## OpenAPI ````yaml /openapi/source/external/email/email.json post /email/ip_pools openapi: 3.0.3 info: x-latency-category: responsive x-endpoint-cost: light title: Telnyx API description: >- Programmable email: sending, templates, validation, events, agent inboxes, drafts, threads, domains & DKIM, suppressions and unsubscribe groups. version: 2.0.0 contact: name: Telnyx url: https://telnyx.com servers: - url: https://api.telnyx.com/v2 security: - BearerAuth: [] tags: - name: Email Validations description: Validate email addresses synchronously or in asynchronous batches. - name: Email Templates description: Create, list, retrieve, update, delete, and render Liquid email templates. - name: Email Messages description: >- Send and manage email messages. Legacy `/v2/emails` routes are aliases for these endpoints. - name: Email Events description: Retrieve account-level email events and event statistics. - name: Email Inboxes description: >- Create and manage agent inboxes, retrieve inbound messages and threads, and reply to or forward messages. - name: Email Drafts description: >- Create, list, retrieve, update, delete, and send unsent draft messages belonging to an agent inbox. - name: Email Threads description: >- Account-wide conversation threads across every inbox, for agents operating many inboxes at once. - name: Email Domains description: Email domain CRUD operations - name: Email Domain DNS Records description: DNS verification records for email domains - name: Email Webhooks description: Per-domain webhook endpoints with event subscriptions - name: Email Suppressions description: Recipient suppression records (`/v2/email_blocks`). - name: Email Suppression Imports description: Async CSV import of competitor suppression lists. - name: Email Unsubscribe Groups description: Named groups and group-scoped suppressions. - name: Dedicated IPs description: >- Purchase and manage dedicated sending IP addresses for your Telnyx email traffic. - name: IP Pools description: Group dedicated IPs into pools for sending. paths: /email/ip_pools: post: tags: - IP Pools summary: Create an IP pool description: >- 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. operationId: createIpPool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IpPoolCreateRequest' example: name: primary-pool is_default: true responses: '201': description: Created IP pool content: application/json: schema: $ref: '#/components/schemas/IpPoolShowResponse' example: data: id: 9b1c4d70-abcd-4e5f-8a9b-0c1d2e3f4a5b record_type: ip_pool name: primary-pool is_default: true domain_id: null ips: [] created_at: '2026-09-30T02:03:09.474123Z' updated_at: '2026-09-30T02:03:09.474123Z' '400': description: Malformed request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: The referenced email domain was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: errors: - code: '10001' title: Not Found detail: The requested email domain was not found '422': description: >- Validation failed: invalid or duplicate `name`, a second default pool, or a `domain_id` owned by another account. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: errors: - code: '10015' title: Validation Failed detail: already has a default pool source: pointer: /data/attributes/account_id components: schemas: IpPoolCreateRequest: type: object required: - name properties: name: type: string description: >- 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: type: boolean description: >- 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: type: string format: uuid description: >- 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. IpPoolShowResponse: type: object properties: data: $ref: '#/components/schemas/IpPool' required: - data ErrorEnvelope: type: object description: Telnyx v2 error envelope. properties: errors: type: array items: type: object properties: code: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string parameter: type: string required: - errors IpPool: type: object description: >- 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`). properties: id: type: string format: uuid record_type: type: string enum: - ip_pool name: type: string description: Pool name, unique within the account. is_default: type: boolean description: >- 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: type: string format: uuid nullable: true description: >- Email domain this pool is scoped to. The pool carries that domain's mail. Null when the pool is not domain-scoped. ips: type: array items: $ref: '#/components/schemas/IpPoolMemberIp' description: >- Member IPs with their routing weights. Populated by Retrieve an IP pool; list, create, and update responses return an empty array. created_at: type: string format: date-time updated_at: type: string format: date-time IpPoolMemberIp: description: >- A dedicated IP as a member of a pool, with its routing weight in this pool. Weight is a positive integer (default 100). allOf: - $ref: '#/components/schemas/DedicatedIp' type: object properties: weight: type: integer minimum: 1 description: Relative routing weight of this IP within the pool. DedicatedIp: type: object description: A dedicated sending IP address owned by the account. properties: id: type: string format: uuid record_type: type: string enum: - dedicated_ip ip_address: type: string description: The allocated IPv4/IPv6 address. ip_version: type: string enum: - ipv4 - ipv6 pool_id: type: string format: uuid nullable: true region: type: string description: Region label of the allocated IP (for example, `ewr-nj1`). status: type: string enum: - provisioning - warming_up - active - suspended - released description: >- 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: $ref: '#/components/schemas/DedicatedIpWarmup' billing: $ref: '#/components/schemas/DedicatedIpBilling' provisioning_status: type: string enum: - not_applicable - pending_ptr - pending_dns - dns_confirmed - dns_lost description: Same value as `provisioning.dns_status`. provisioning: $ref: '#/components/schemas/DedicatedIpProvisioning' ptr_hostname: type: string nullable: true description: >- Telnyx-managed reverse DNS (PTR) hostname of the IP, in the form `mta-.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: type: string format: date-time nullable: true description: >- When the PTR hostname was forward-confirmed (PTR → hostname → A record → this IP). The IP carries mail only while this is set. quarantine_until: type: string format: date-time nullable: true description: >- Set on release to 30 days after `released_at`. The address is not returned to stock before this time. released_at: type: string format: date-time nullable: true description: When the IP was released. Null until release. suspension_reason: type: string nullable: true description: >- Reason Telnyx recorded when suspending the IP. Null unless `status` is `suspended`. created_at: type: string format: date-time updated_at: type: string format: date-time DedicatedIpWarmup: type: object description: Warmup ramp state for a dedicated IP. properties: started_at: type: string format: date-time nullable: true description: >- When `start_warmup` was called. Null before warm-up starts and after release. progress: type: integer description: >- 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. minimum: 0 maximum: 100 daily_cap: type: integer nullable: true minimum: 1 description: >- 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: type: boolean description: True while the ramp is paused. paused_at: type: string format: date-time nullable: true description: When the ramp was paused. Null when not paused. today: type: object nullable: true description: >- 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`. properties: day: type: string format: date description: >- The UTC day this snapshot describes (warmup caps reset at UTC midnight). cap: type: integer nullable: true description: >- 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: type: integer description: >- First-attempt sends released from warmup hold so far today. Delivery retries never lease allowance and are not counted. remaining: type: integer nullable: true description: >- 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. DedicatedIpBilling: type: object description: Monthly recurring charge (MRC) state for the IP's current allocation. properties: status: type: string enum: - not_started - pending - in_progress - active - stopping - stopped - stop_failed - failed description: >- `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: type: boolean description: >- True when `status` is `active`, `stopping`, or `stop_failed`. An IP carries mail only after its charge has been created. DedicatedIpProvisioning: type: object description: >- Read-only status of the Telnyx-managed PTR record. No customer action is required to complete it. properties: dns_status: type: string enum: - not_applicable - pending_ptr - pending_dns - dns_confirmed - dns_lost description: >- `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: type: string nullable: true enum: - pending - pr_open - merged - confirmed - failed - abandoned - null description: >- State of the Telnyx PTR change: `pending`, `pr_open`, `merged`, `confirmed`, `failed`, or `abandoned`. Informational. ptr_request_pr_url: type: string nullable: true description: >- Reference to the Telnyx PTR change request, when one exists. Informational. checklist: type: object properties: ptr_requested: type: boolean ptr_authored: type: boolean ptr_merged: type: boolean forward_confirmed: type: boolean description: >- 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. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Telnyx API key supplied as `Authorization: Bearer `. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers. ````