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 <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.

POST

email_domains

{domain_id}

rotate_dkim

JavaScript

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);

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)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.EmailDomains.RotateDkim(
		context.TODO(),
		"domain_id",
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

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");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->emailDomains->rotateDkim(
    'domain_id',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "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"
      }
    ]
  }
}

{
  "errors": [
    {
      "code": "10008",
      "title": "Forbidden",
      "detail": "Shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account"
    }
  ]
}

{
  "errors": [
    {
      "code": "10001",
      "title": "Not Found",
      "detail": "The requested email domain was not found"
    }
  ]
}

{
  "errors": [
    {
      "code": "40901",
      "title": "Conflict",
      "detail": "DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry."
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Validation Failed",
      "detail": "domain is invalid",
      "source": {
        "pointer": "/data/attributes/domain"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "500",
      "title": "Internal Server Error",
      "detail": "An unexpected error occurred"
    }
  ]
}

Authorizations

Authorization

string

header

required

Telnyx API key supplied as Authorization: Bearer <token>. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.

Path Parameters

domain_id

string<uuid>

required

Email domain UUID

Response

DKIM key rotated

data

object

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.

Show child attributes

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"
    }
  ]
}

JavaScript

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);

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)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.EmailDomains.RotateDkim(
		context.TODO(),
		"domain_id",
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

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");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->emailDomains->rotateDkim(
    'domain_id',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "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"
      }
    ]
  }
}

{
  "errors": [
    {
      "code": "10008",
      "title": "Forbidden",
      "detail": "Shared email domains are managed by Telnyx and cannot have their DKIM keys rotated by this account"
    }
  ]
}

{
  "errors": [
    {
      "code": "10001",
      "title": "Not Found",
      "detail": "The requested email domain was not found"
    }
  ]
}

{
  "errors": [
    {
      "code": "40901",
      "title": "Conflict",
      "detail": "DKIM rotation conflicted with a concurrent operation on this domain. Safe to retry."
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Validation Failed",
      "detail": "domain is invalid",
      "source": {
        "pointer": "/data/attributes/domain"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "500",
      "title": "Internal Server Error",
      "detail": "An unexpected error occurred"
    }
  ]
}

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

For AI Agents

Rotate the DKIM key for an email domain

Authorizations

Path Parameters

Response