---
title: "Rotate the DKIM key for an email domain"
method: POST
path: "/email_domains/{domain_id}/rotate_dkim"
tags: ["Email Domains"]
---

# Rotate the DKIM key for an email domain

`POST /email_domains/{domain_id}/rotate_dkim`

Generates a new DKIM key for the domain, activates it, and retires the previous key. The response includes the updated DKIM DNS records the customer must publish. Selectors are fixed, so rotation replaces the TXT value at the existing `<selector>._domainkey.<domain>` host rather than adding a second record — `old_selector_retained` is false and the new TXT value must be published promptly, since signing switches to the new key immediately and the old TXT value will no longer match. The previous key is retired to a `retiring` state (retained, not revoked) so it can be revoked after the DNS propagation grace period.

## Path parameters

- `domain_id` string, uuid, required

## Response `201`

DKIM key rotated

- EmailDomainDKIMRotationResponse
  - `data` EmailDomainDKIMRotation, required — Result of rotating a domain's DKIM key. The new key is active and signing switches to it immediately; the previous key is retired to a `retiring` state (retained, not revoked) so it can be revoked after the DNS propagation grace period. Selectors are fixed, so the DKIM DNS record's TXT value is replaced in place at the shared `<selector>._domainkey.<domain>` host — `old_selector_retained` is false and the returned dns_records carry the new value the customer must publish promptly.
    - `record_type` 'email_domain_dkim_rotation', required
    - `domain_id` string, uuid, required
    - `domain` string, required
    - `dkim` object, required — The new active DKIM key.
      - `id` string, uuid, required
      - `selector` string, required
      - `algorithm` 'rsa-sha256', required
      - `key_length` 2048, required
      - `version` integer, required — Monotonically increasing per-domain key version.
      - `status` 'active', required
      - `activated_at` string, date-time, nullable
    - `previous_dkim_key` object, nullable, required — The retired previous key, or null when the domain had no active key before rotation. Retained in a `retiring` state so it can be revoked after the DNS propagation grace period.
      - `id` string, uuid, required
      - `selector` string, required
      - `version` integer, required
      - `status` 'retiring' | 'revoked', required
    - `old_selector_retained` boolean, required — False for this service: one selector is fixed per domain, so rotation replaces the TXT value at the existing _domainkey host. There is no dual-selector overlap; publish the replacement TXT promptly because signing switches immediately.
    - `dns_records` DNSRecord[], required — The DKIM DNS records the customer must publish, carrying the new key's TXT value with verification reset to pending.
      - `id` string, uuid, required
      - `purpose` 'ownership' | 'spf' | 'dkim' | 'dmarc' | 'mx', required
      - `record_type` 'TXT' | 'MX', required
      - `host` string, required
      - `value` string, required
      - `actual_value` string, nullable
      - `priority` integer, nullable
      - `required` boolean, required
      - `status` 'pending' | 'verified' | 'failed' | 'not_required', required

## Other responses

- `403` — Forbidden — shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account.
- `404` — Resource not found
- `409` — DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry.
- `422` — Validation failed
- `500` — Internal server error

## Changes

> 93 revisions in range; 1 not diffed.

- **2026-09-23** `16bfa298dc71` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/email_domains/:domain_id/rotate_dkim/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/88481995b4ca?raw)