From 68b8b9df74cf1dad68b6f6a1eb7d437fd6464b8f Mon Sep 17 00:00:00 2001
From: Fernando Silveira <104788690+seewerah@users.noreply.github.com>
Date: Thu, 14 May 2026 10:05:05 -0300
Subject: [PATCH] docs(sending-domains): default new DKIM keys to 2048 bits and
surface dkim_key_length (SparkPost/Momentum#1241)
Update the Sending Domains API blueprint to match the API change in
SparkPost/Momentum#1241: the implicit default DKIM key length is now
2048 bits on both POST /sending-domains and POST
/sending-domains/{domain}/dkim-keys, and DKIM-key read paths (POST
create, single GET, list GET, PUT update) now include a
dkim_key_length field derived from the stored public key's RSA
modulus.
Update the dkim_key_length parameter description to lead with the
2048-bit default, frame the multi-string TXT record requirement
around the new default (and note that mainstream DNS providers handle
the split automatically), and surface the explicit 1024-bit override
as an escape hatch for providers that don't. Add dkim_key_length to
the DKIM Key Object schema, its sample payload, and the DKIM Key
Constraints table. Update every DKIM-key sub-resource response
example (list, create-auto, create-user-keys, single GET, PUT
header-only update, PUT full key replacement) to include
"dkim_key_length": 2048 so customers reading the docs see the field
they will actually receive.
---
content/api/sending-domains.apib | 20 +++++++++++++++-----
1 file changed, 15 insertions(+), 5 deletions(-)
diff --git a/content/api/sending-domains.apib b/content/api/sending-domains.apib
index c2d4f8af..4646ca1c 100644
--- a/content/api/sending-domains.apib
+++ b/content/api/sending-domains.apib
@@ -145,8 +145,8 @@ Creates a new sending domain. Each domain and its subdomains can only be added t
+ headers (string) - Header fields to be included in the DKIM signature. **This field is currently ignored.**
+ generate_dkim (boolean) - Whether to generate a DKIM keypair on creation.
+ Default: true
- + dkim_key_length (number) - Size, in bits, of the DKIM private key to be generated. This option only applies if `generate_dkim` is true.
Note public keys for private keys longer than 1024 bits will be longer than 255 characters. Because of this, the public key TXT record in DNS will need to contain multiple strings, see RFC 7208, section 3.3 for an example of how the SPF spec addresses this.
- + Default: 1024
+ + dkim_key_length (number) - Size, in bits, of the DKIM private key to be generated. This option only applies if `generate_dkim` is true. New sending domains default to a 2048-bit key; pass `1024` here if your DNS provider does not support multi-string TXT records.
Note public keys for private keys longer than 1024 bits (including the new 2048-bit default, which yields TXT values around 400 characters) exceed the single-string TXT record limit of 255 characters. The public key TXT record in DNS must therefore contain multiple quoted strings; see RFC 7208, section 3.3 for an example of how the SPF spec addresses the same constraint. Most modern DNS providers (Route 53, Cloudflare, Google Cloud DNS, Azure DNS) split long TXT records automatically.
+ + Default: 2048
+ shared_with_subaccounts (boolean) - Whether this domain can be used by subaccounts. Only available to domains belonging to a primary account.
+ Default: false
@@ -579,6 +579,7 @@ These endpoints manage additional DKIM keys for sending domains. Each sending do
+ headers (string) - Colon-separated list of headers to sign.
+ dkim_status: unverified, pending, valid, invalid (enum) - Verification status of the DKIM key.
+ is_default (boolean) - Whether this is the default key for the domain.
+ + dkim_key_length (number) - Size, in bits, of the RSA modulus of the stored DKIM key (e.g. `2048`). Derived from the public key on each read, so it always reflects the actual key currently in use for the domain.
+ created_at (string) - ISO 8601 timestamp of creation. Not present for default keys.
+ updated_at (string) - ISO 8601 timestamp of last update. Not present for default keys.
+ dns (object) - DNS record information. Included in single key GET, POST create, POST verify, and PUT update responses.
@@ -596,6 +597,7 @@ These endpoints manage additional DKIM keys for sending domains. Each sending do
"headers": "from:to:subject:date",
"dkim_status": "valid",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T14:00:00Z"
}
@@ -611,6 +613,7 @@ These endpoints manage additional DKIM keys for sending domains. Each sending do
| Reserved key IDs | `default` |
| Immutable fields | `id` |
| Key length range | 1024-4096 bits |
+| Default key length | 2048 bits |
#### DNS Verification Requirements
@@ -681,7 +684,8 @@ The default key is always first in the list and does not have `created_at` or `u
"selector": "scph0820",
"headers": "from:to:subject:date",
"dkim_status": "valid",
- "is_default": true
+ "is_default": true,
+ "dkim_key_length": 2048
},
{
"id": "marketing",
@@ -691,6 +695,7 @@ The default key is always first in the list and does not have `created_at` or `u
"headers": "from:to:subject:date",
"dkim_status": "valid",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T14:00:00Z"
}
@@ -725,8 +730,8 @@ When providing your own keys, all three fields (`private`, `public`, `selector`)
+ private (string) - User-provided private key. Requires `public` and `selector`.
+ public (string) - User-provided public key. Requires `private` and `selector`.
+ selector (string) - User-provided selector. Requires `private` and `public`.
- + dkim_key_length (number) - Key length for auto-generation (1024-4096).
- + Default: 1024
+ + dkim_key_length (number) - Key length, in bits, for auto-generation. Must be between 1024 and 4096. New keys default to 2048; pass `1024` only if your DNS provider does not support multi-string TXT records.
+ + Default: 2048
+ Parameters
+ domain (required, string, `example.com`)
@@ -756,6 +761,7 @@ When providing your own keys, all three fields (`private`, `public`, `selector`)
"headers": "from:to:subject:date",
"dkim_status": "unverified",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T14:00:00Z",
"dns": {
@@ -791,6 +797,7 @@ When providing your own keys, all three fields (`private`, `public`, `selector`)
"headers": "from:to:subject:date",
"dkim_status": "unverified",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T14:00:00Z",
"dns": {
@@ -889,6 +896,7 @@ Using `key_id` of "default" returns the domain's primary DKIM key. The default k
"headers": "from:to:subject:date",
"dkim_status": "valid",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T14:00:00Z",
"dns": {
@@ -954,6 +962,7 @@ Changing `signing_domain` or key fields resets `dkim_status` to `unverified`.
"headers": "from:to:subject:date:reply-to",
"dkim_status": "valid",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T16:30:00Z",
"dns": {
@@ -989,6 +998,7 @@ Changing `signing_domain` or key fields resets `dkim_status` to `unverified`.
"headers": "from:to:subject:date",
"dkim_status": "unverified",
"is_default": false,
+ "dkim_key_length": 2048,
"created_at": "2025-01-25T14:00:00Z",
"updated_at": "2025-01-25T16:30:00Z",
"dns": {