Skip to content

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

Open
seewerah wants to merge 1 commit into
mainfrom
feat/dkim-2048-default-1241
Open

docs(sending-domains): default new DKIM keys to 2048 bits (SparkPost/Momentum#1241)#577
seewerah wants to merge 1 commit into
mainfrom
feat/dkim-2048-default-1241

Conversation

@seewerah
Copy link
Copy Markdown
Contributor

@seewerah seewerah commented May 14, 2026

Summary

  • Update the dkim_key_length parameter on POST /v1/sending-domains and on POST /v1/sending-domains/{domain}/dkim-keys to document the new 2048-bit default and frame the 1024-bit value as an opt-in escape hatch for DNS providers that can't return multi-string TXT records.
  • Reframe the existing TXT-record-length note around the new default: 2048-bit public keys produce TXT values ~400 characters long, which exceed the 255-character single-string TXT limit and must therefore be returned as multiple quoted strings; mainstream managed-DNS providers (Route 53, Cloudflare, Google Cloud DNS, Azure DNS) do this split automatically.
  • Document the new dkim_key_length field that now appears on every DKIM-key read path (POST create, single GET, list GET, PUT update) in SparkPost/Momentum#1241: add it to the DKIM Key Object schema, the sample payload, the DKIM Key Constraints table (new "Default key length: 2048 bits" row), and every response example for the dkim-keys sub-resource so the docs match what the API actually returns.

Why

Matches the behavior change shipping in SparkPost/Momentum#1241. Without these doc updates, customers reading the page would still see "Default: 1024" and would be surprised by a TXT record longer than the docs prepare them for, and the new response field would be undocumented. 2048-bit RSA is the modern DKIM baseline (accepted/preferred by Gmail, Microsoft, Yahoo) and matches what mcp-server-sparkpost already does for newly created domains.

Scope notes

  • The Momentum PR exposes dkim_key_length on the dkim-keys sub-resource responses only. The dkim sub-object returned by the parent POST /sending-domains response was intentionally left as-is in Momentum, so the parent-endpoint response examples here are not updated to include dkim_key_length. If we later decide to surface it on the parent endpoint's dkim sub-object too, a follow-up doc PR can cover those samples.
  • This PR is docs-only. No code paths in this repo are touched.

Test plan

  • Render the Sending Domains page locally (or in Netlify preview) and spot-check that:
    • The dkim_key_length parameter blocks on both create endpoints render with "Default: 2048" and the rewritten DNS note.
    • The DKIM Key Object schema, sample payload, and Constraints table all show dkim_key_length.
    • Every dkim-keys response example (list / create-auto / create-user-keys / single GET / PUT header-only / PUT full replacement) shows "dkim_key_length": 2048.
  • Confirm no Markdown/apib parse warnings in the build.
  • (Optional) Diff render with main to confirm parent-endpoint examples are untouched.

… 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants