Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Check DKIM, SPF and DMARC for a domain

GET /api/v2/shared-hosting/{accountId}/email-deliverability

Checks the DKIM, SPF and DMARC records of a domain on the web hosting account, as cPanel’s Email Deliverability check sees them. dkim.requiredValue is the exact TXT value to publish at dkim.name. decision and nextAction.code say whether anything needs to change. The call only reads. It does not create DKIM keys or change DNS. spf.state: valid_hostup_policy means the SPF record uses Hostup’s include:spf.hostup.se. cPanel still reports a warning for it. Keep that record as it is.

Authentication: An API key with the scopes read:hosting and console:services. About keys and scopes

Request

Path parameters

accountIdstringrequired
The hosting account ID (acct_…).

Query parameters

domainstringrequired
Domain on the hosting account. Unicode IDN and punycode spellings are both accepted.

Example

GET /api/v2/shared-hosting/{accountId}/email-deliverability
curl "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliverability?domain=example.com" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 DKIM, SPF and DMARC as cPanel validates them.

Response 200
{
  "domain": "example.com",
  "readOnly": true,
  "source": "cpanel_emailauth",
  "dkim": {
    "state": "valid",
    "cpanelState": "VALID",
    "name": "default._domainkey.example.com",
    "type": "TXT",
    "requiredValue": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh...;",
    "currentValues": [
      "v=DKIM1; k=rsa; p=MIIBIjANBgkqh...;"
    ],
    "matchesRequired": true,
    "error": null
  },
  "spf": {
    "state": "valid_hostup_policy",
    "cpanelState": "INVALID",
    "name": "example.com",
    "type": "TXT",
    "cpanelRequiredMechanisms": "ip4:192.0.2.23 include:relay.mailchannels.net",
    "currentValues": [
      "v=spf1 mx include:spf.hostup.se ~all"
    ],
    "sendingIp": "192.0.2.23",
    "hostupPolicyDetected": true,
    "explanation": "cPanel reports its generated direct IP and MailChannels mechanisms as missing, but this domain uses HostUp's centralized include:spf.hostup.se policy, which intentionally covers that HostUp sending path. Do not replace it with cPanel's expanded suggestion.",
    "error": null
  },
  "dmarc": {
    "state": "valid_with_cpanel_spf_warning",
    "cpanelState": "SPF_ERROR",
    "name": "_dmarc.example.com",
    "type": "TXT",
    "currentValue": "v=DMARC1; p=quarantine",
    "explanation": "The DMARC TXT record is present. cPanel's DMARC warning is inherited from the same SPF mechanism-comparison warning, not from a missing DMARC record.",
    "error": "SPF record not valid"
  },
  "decision": "configured",
  "nextAction": {
    "code": "none",
    "message": "No DNS change is required from this cPanel Email Deliverability result."
  }
}
Response fields
domainstring
The domain checked.
readOnlyboolean
Always true. The call changes nothing. One of true.
sourcestring
Always cpanel_emailauth: the result comes from cPanel’s Email Deliverability check. One of cpanel_emailauth.
dkimobject
The DKIM record.
statestring
valid, missing (no DKIM record published), invalid or unknown. One of valid, missing, invalid, unknown.
cpanelStatestring
cPanel’s own result, for example VALID.
namestring or null
Host name of the DKIM TXT record.
typestring
Always TXT. One of TXT.
requiredValuestring or null
The exact TXT value cPanel expects. null when the domain has no DKIM key yet.
currentValuesarray of string
TXT values published now.
matchesRequiredboolean
true when a published value equals requiredValue.
errorstring or null
cPanel’s error text, if any.
spfobject
The SPF record.
statestring
valid, valid_hostup_policy (the record uses include:spf.hostup.se; keep it), missing, invalid or unknown. One of valid, valid_hostup_policy, missing, invalid, unknown.
cpanelStatestring
cPanel’s own result, for example INVALID.
namestring
Host name of the SPF TXT record.
typestring
Always TXT. One of TXT.
cpanelRequiredMechanismsstring or null
The mechanisms cPanel expects in the SPF record.
currentValuesarray of string
SPF values published now.
sendingIpstring or null
IP address the hosting server sends mail from.
hostupPolicyDetectedboolean
true when the one SPF record uses include:spf.hostup.se.
explanationstring or null
Why state differs from cPanel’s own result. null otherwise.
errorstring or null
cPanel’s error text, if any.
dmarcobject
The DMARC record.
statestring
valid, valid_with_cpanel_spf_warning (the DMARC record is present; cPanel’s warning comes from the SPF check), missing, invalid or unknown. One of valid, valid_with_cpanel_spf_warning, missing, invalid, unknown.
cpanelStatestring
cPanel’s own result, for example SPF_ERROR.
namestring
Host name of the DMARC TXT record.
typestring
Always TXT. One of TXT.
currentValuestring or null
The DMARC value published now.
explanationstring or null
Why state differs from cPanel’s own result. null otherwise.
errorstring or null
cPanel’s error text, if any.
decisionstring
configured: nothing to change. action_required: see nextAction. unavailable: cPanel returned too little data. Try again. One of configured, action_required, unavailable.
nextActionobject
What to do next.
codestring
none, publish_dkim (publish dkim.requiredValue at dkim.name), generate_dkim_key (create the domain’s DKIM key in cPanel first), review_spf, review_dmarc or retry_later. One of none, publish_dkim, generate_dkim_key, review_spf, review_dmarc, retry_later.
messagestring
The same advice in words.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400domain is missing or not a valid domain name.
401Unauthorized. Authentication is required.
403The domain is not on this hosting account (domain_not_owned), the API key lacks a required scope or the account is not active.
404Not found. The resource does not exist or is not owned by the caller.
409The account is on Hostup’s previous hosting platform. The records cannot be checked there through the API.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502cPanel’s check could not be read right now. Try again.

This page as MarkdownOpenAPI spec