Skip to content

docs(sending-domains): default new DKIM keys to 2048 bits (SparkPost/Momentum#1241) #577

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
seewerah merged 1 commit into from
May 20, 2026
Merged

docs(sending-domains): default new DKIM keys to 2048 bits (SparkPost/Momentum#1241) #577

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions content/api/sending-domains.apib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. <br /><span class="label label-info"><strong>Note</strong></span> public keys for private keys longer than 1024 bits will be longer than 255 characters. Because of this, the public key <code>TXT</code> record in DNS will need to contain multiple strings, see <a href="https://tools.ietf.org/html/rfc7208#section-3.3">RFC 7208, section 3.3</a> 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. <br /><span class="label label-info"><strong>Note</strong></span> 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 <code>TXT</code> record in DNS must therefore contain multiple quoted strings; see <a href="https://tools.ietf.org/html/rfc7208#section-3.3">RFC 7208, section 3.3</a> 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

Expand Down Expand Up @@ -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.
Expand All @@ -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"
}
Expand All @@ -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
Expand Down Expand Up @@ -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",
Expand All @@ -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"
}
Expand Down Expand Up @@ -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`)
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down