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": {