> ## 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. # Rotate the DKIM key for an email domain > 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 `._domainkey.` 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. ## OpenAPI ````yaml /openapi/source/external/email/email.json post /email_domains/{domain_id}/rotate_dkim 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. paths: /email_domains/{domain_id}/rotate_dkim: post: tags: - Email Domains summary: Rotate the DKIM key for an email domain description: > 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 `._domainkey.` 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. operationId: rotateEmailDomainDKIMKey parameters: - $ref: '#/components/parameters/EmailDomainDomainId' responses: '201': description: DKIM key rotated content: application/json: schema: $ref: '#/components/schemas/EmailDomainDKIMRotationResponse' example: data: record_type: email_domain_dkim_rotation domain_id: 123e4567-e89b-12d3-a456-426614174002 domain: example.com dkim: id: 123e4567-e89b-12d3-a456-42661417400a selector: telnyx1 algorithm: rsa-sha256 key_length: 2048 version: 2 status: active activated_at: '2026-09-11T12:00:00Z' previous_dkim_key: id: 123e4567-e89b-12d3-a456-426614174009 selector: telnyx1 version: 1 status: retiring old_selector_retained: false dns_records: - id: 123e4567-e89b-12d3-a456-42661417400b purpose: dkim record_type: TXT host: telnyx1._domainkey.example.com value: v=DKIM1; k=rsa; p=MIIBIjANBgkqh... actual_value: null priority: null required: true status: pending '403': description: > Forbidden — shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account. content: application/json: schema: $ref: '#/components/schemas/DomainsErrorResponse' example: errors: - code: '10008' title: Forbidden detail: >- Shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account '404': $ref: '#/components/responses/NotFound' '409': description: >- DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry. content: application/json: schema: $ref: '#/components/schemas/DomainsErrorResponse' example: errors: - code: '40901' title: Conflict detail: >- DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry. '422': $ref: '#/components/responses/ValidationFailed' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const response = await client.emailDomains.rotateDkim('domain_id'); console.log(response.data); - lang: Python source: | import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) response = client.email_domains.rotate_dkim( "domain_id", ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.EmailDomains.RotateDkim(\n\t\tcontext.TODO(),\n\t\t\"domain_id\",\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); var response = client.emailDomains().rotateDkim("domain_id"); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.email_domains.rotate_dkim("domain_id") puts(response) - lang: PHP source: >- emailDomains->rotateDkim( 'domain_id', ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx email-domains rotate-dkim \ --api-key 'My API Key' \ --domain-id domain_id components: parameters: EmailDomainDomainId: name: domain_id in: path required: true description: Email domain UUID schema: type: string format: uuid schemas: EmailDomainDKIMRotationResponse: type: object required: - data properties: data: $ref: '#/components/schemas/EmailDomainDKIMRotation' DomainsErrorResponse: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Error' EmailDomainDKIMRotation: type: object description: > 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 `._domainkey.` host — `old_selector_retained` is false and the returned dns_records carry the new value the customer must publish promptly. required: - record_type - domain_id - domain - dkim - previous_dkim_key - old_selector_retained - dns_records properties: record_type: type: string enum: - email_domain_dkim_rotation domain_id: type: string format: uuid domain: type: string dkim: type: object description: The new active DKIM key. required: - id - selector - algorithm - key_length - version - status properties: id: type: string format: uuid selector: type: string algorithm: type: string enum: - rsa-sha256 key_length: type: integer enum: - 2048 version: type: integer description: Monotonically increasing per-domain key version. minimum: 1 status: type: string enum: - active activated_at: type: string format: date-time nullable: true previous_dkim_key: type: object nullable: true description: > 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. required: - id - selector - version - status properties: id: type: string format: uuid selector: type: string version: type: integer status: type: string enum: - retiring - revoked old_selector_retained: type: boolean description: >- 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: type: array description: > The DKIM DNS records the customer must publish, carrying the new key's TXT value with verification reset to pending. items: $ref: '#/components/schemas/DNSRecord' example: record_type: email_domain_dkim_rotation domain_id: 123e4567-e89b-12d3-a456-426614174002 domain: example.com dkim: id: 123e4567-e89b-12d3-a456-42661417400a selector: telnyx1 algorithm: rsa-sha256 key_length: 2048 version: 2 status: active activated_at: '2026-09-11T12:00:00Z' previous_dkim_key: id: 123e4567-e89b-12d3-a456-426614174009 selector: telnyx1 version: 1 status: retiring old_selector_retained: false dns_records: - id: 123e4567-e89b-12d3-a456-42661417400b purpose: dkim record_type: TXT host: telnyx1._domainkey.example.com value: v=DKIM1; k=rsa; p=MIIBIjANBgkqh... actual_value: null priority: null required: true status: pending Error: type: object required: - code - title - detail properties: code: type: string enum: - '10001' - '10015' - '500' - '10007' - '10008' - '10020' - '40901' title: type: string detail: type: string source: type: object properties: pointer: type: string DNSRecord: type: object required: - id - purpose - record_type - host - value - required - status properties: id: type: string format: uuid purpose: type: string enum: - ownership - spf - dkim - dmarc - mx record_type: type: string enum: - TXT - MX host: type: string value: type: string actual_value: type: string nullable: true priority: type: integer nullable: true required: type: boolean status: type: string enum: - pending - verified - failed - not_required example: id: 123e4567-e89b-12d3-a456-426614174001 purpose: ownership record_type: TXT host: _telnyx-email.example.com value: telnyx-domain-verification=abc123 actual_value: null priority: null required: true status: pending responses: NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/DomainsErrorResponse' example: errors: - code: '10001' title: Not Found detail: The requested email domain was not found ValidationFailed: description: Validation failed content: application/json: schema: $ref: '#/components/schemas/DomainsErrorResponse' example: errors: - code: '10015' title: Validation Failed detail: domain is invalid source: pointer: /data/attributes/domain InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/DomainsErrorResponse' example: errors: - code: '500' title: Internal Server Error detail: An unexpected error occurred 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. ````