---
title: "Update a dedicated IP"
method: PATCH
path: "/email/dedicated_ips/{id}"
tags: ["Dedicated IPs"]
---

# Update a dedicated IP

`PATCH /email/dedicated_ips/{id}`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/email/dedicated_ips/{id}`
- Auth: HTTP bearer

Move the IP to another pool, or pause/resume its warm-up ramp. One change applies per request. `pool_id` takes precedence over warm-up changes. Otherwise, use `warmup_paused` or `warmup.paused`; a Boolean `warmup_paused` takes precedence. Moving the last IP out of a pool requires `force: true` and `drain: true`. The PTR hostname is managed by Telnyx: a request that includes `ptr_hostname` returns `422` unless `pool_id` or a warm-up field is present, in which case `ptr_hostname` is ignored.

## Path parameters

- `id` string, uuid, required

## Request body

- DedicatedIpUpdateRequest: Applies one change per request. `pool_id` takes precedence over warm-up changes: when it is present, the IP moves to that pool (with `weight`, `force`, and `drain`) and other fields are ignored. Otherwise, use `warmup_paused` or `warmup.paused`; a Boolean `warmup_paused` takes precedence. The PTR hostname is managed by Telnyx and cannot be changed: when neither `pool_id` nor a warm-up field is present, a body that includes `ptr_hostname` (including `null`) returns `422` and the IP is unchanged. A body with none of these fields returns the IP unchanged.
  - `pool_id` string, uuid: Move the IP to this pool, replacing its current membership. Use the IP's current pool to change only its weight. To take an IP out of a pool, use `DELETE /email/ip_pools/{id}/ips/{ip_id}`.
  - `weight` integer: Routing weight in the target pool. Used only with `pool_id`.
  - `force` boolean: Set together with `drain: true` to move the last IP out of its current pool. Used only with `pool_id`.
  - `drain` boolean: Set together with `force: true` to move the last IP out of its current pool. Acknowledges that mail routed to the emptied pool is held. Used only with `pool_id`.
  - `warmup_paused` boolean: Pause (`true`) or resume (`false`) the warm-up ramp; equivalent to the `pause_warmup` and `resume_warmup` actions. A Boolean value takes precedence over `warmup.paused`. When a pause field is present and `pool_id` is absent, supplying neither pause field as a Boolean invokes resume.
  - `warmup` object: Alias for `warmup_paused`.
    - `paused` boolean: Pause (`true`) or resume (`false`) the warm-up ramp. Used only when `warmup_paused` is not a Boolean.

## Response `200`

Updated dedicated IP

- DedicatedIpShowResponse
  - `data` DedicatedIp, required: A dedicated sending IP address owned by the account.
    - `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

## Other responses

- `400`: Malformed request
- `401`: Unauthorized
- `404`: The dedicated IP or the target pool was not found.
- `409`: The IP is the last member of its current pool and `force`/`drain` were not both set, or `warmup_paused` or `warmup.paused` was sent for an IP that is not `warming_up`.
- `422`: Validation failed. Pool reassignment rejects invalid weights and released IPs. A request that includes `ptr_hostname` (any value, including `null`) and neither `pool_id` nor a warm-up field is rejected because the PTR hostname is managed by Telnyx; the IP is unchanged.

## 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/dedicated_ips/:id/patch.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)