DKIM Selectors

List, register and remove the DKIM selectors MailShield knows about for a domain.

DKIM signatures are published under a selector, for example postal-kpfi6p._domainkey.example.com. There is no way to enumerate selectors from DNS, so MailShield discovers them from inbound DMARC reports. If you already know a selector, register it here and it is checked immediately instead of waiting for the first report to arrive.

List Selectors

GET /api/v1/domains/{id}/dkim/selectors

Path Parameters

Parameter	Type	Description
id	uuid	Domain ID

Response

{
  "data": [
    {
      "selector": "postal-kpfi6p",
      "signingDomain": null,
      "valid": true,
      "keyType": "rsa",
      "keySize": 2048,
      "addedManually": true,
      "errors": [],
      "warnings": [],
      "checkedAt": "2024-01-15T10:30:00Z"
    },
    {
      "selector": "pic",
      "signingDomain": "mg.example.com",
      "valid": true,
      "keyType": "rsa",
      "keySize": 2048,
      "addedManually": false,
      "errors": [],
      "warnings": [],
      "checkedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Returns the latest check per selector. addedManually is true for selectors registered through the API or dashboard, and false for ones discovered from reports. signingDomain is the subdomain the key is published under, for a selector a subdomain signs its own mail with (mg.example.com above, whose key is at pic._domainkey.mg.example.com), and null for keys under the domain itself.

Example

curl -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000/dkim/selectors

---

Register a Selector

POST /api/v1/domains/{id}/dkim/selectors

Request Body

Field	Type	Required	Description
selector	string	Yes	The selector name, e.g. postal-kpfi6p. Letters, numbers, hyphens and underscores only

Give the selector on its own, not the full record name: s1, not s1._domainkey.example.com.

Response (201 Created)

{
  "data": {
    "selector": "postal-kpfi6p",
    "valid": true,
    "keyType": "rsa",
    "keySize": 2048,
    "errors": [],
    "warnings": []
  }
}

The selector is resolved against DNS as part of the request. A selector that does not resolve, or resolves to an invalid key, is still registered with valid: false and the reasons in errors, so you can see why it failed rather than getting a silent no-op.

If the DNS lookup itself failed, the response also has lookupFailed: true. In that case valid: false says nothing about the key: the selector stays registered and is checked again on the next run.

Example

curl -X POST \
  -H "Authorization: Bearer ms_your_token" \
  -H "Content-Type: application/json" \
  -d '{"selector": "postal-kpfi6p"}' \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000/dkim/selectors

Errors

• 400 - Missing selector, or characters outside A-Z a-z 0-9 _ -
• 403 - The token is read-only
• 404 - Domain not found
• 409 - That selector is already registered for this domain

---

Remove a Selector

DELETE /api/v1/domains/{id}/dkim/selectors/{selector}

Path Parameters

Parameter	Type	Description
id	uuid	Domain ID
selector	string	The selector to remove

Response

{
  "data": {
    "selector": "postal-kpfi6p",
    "deleted": true
  }
}

Example

curl -X DELETE \
  -H "Authorization: Bearer ms_your_token" \
  https://app.mailshield.app/api/v1/domains/550e8400-e29b-41d4-a716-446655440000/dkim/selectors/postal-kpfi6p

Errors

• 404 - Domain not found, or no such selector on this domain

Removing a selector deletes its check history. If the selector is still publishing signatures, it will reappear the next time a DMARC report references it.

---

No selectors known vs nothing signing

An empty list is ambiguous on its own, and the two cases need different fixes:

• Nothing has been discovered yet. The domain signs its mail, but no DMARC report naming a selector has arrived. Register the selector directly if you know it: that is what this endpoint is for.
• The domain does not sign at all. No selector will ever appear, because there is nothing to discover. Reports will not help.

If you administer the sending platform you usually know which it is. Common selectors worth trying: default, dkim, google, s1, s2, selector1, selector2, and provider-prefixed ones such as postal-<id>. Registering a selector that does not resolve is harmless: it comes back valid: false with the reason, which is itself the answer to which case you are in.