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

**Check DKIM, SPF and DMARC for a domain**

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.

### Related Endpoints

- `GET /api/v2/shared-hosting/{accountId}`: Get a web hosting account
- `PATCH /api/v2/shared-hosting/{accountId}`: Rename a web hosting account
- `GET /api/v2/shared-hosting/{accountId}/php`: Get PHP versions per website

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scopes: `read:hosting`, `console:services`

### Parameters

- `accountId` (path, string, required): The hosting account ID (`acct_…`). Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `domain` (query, string, required): Domain on the hosting account. Unicode IDN and punycode spellings are both accepted. Example: `example.com`

### Request Example

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

### Response Schema

- `domain` (string, required): The domain checked. Example: `example.com`
- `readOnly` (boolean, required): Always `true`. The call changes nothing.
  Allowed values: true
- `source` (string, required): Always `cpanel_emailauth`: the result comes from cPanel's Email Deliverability check.
  Allowed values: cpanel_emailauth
- `dkim` (object, required): The DKIM record.
- `dkim.state` (string, required): `valid`, `missing` (no DKIM record published), `invalid` or `unknown`.
  Allowed values: valid, missing, invalid, unknown
- `dkim.cpanelState` (string, required): cPanel's own result, for example `VALID`. Example: `VALID`
- `dkim.name` (string, required, nullable): Host name of the DKIM TXT record. Example: `default._domainkey.example.com`
- `dkim.type` (string, required): Always `TXT`.
  Allowed values: TXT
- `dkim.requiredValue` (string, required, nullable): The exact TXT value cPanel expects. `null` when the domain has no DKIM key yet. Example: `v=DKIM1; k=rsa; p=MIIBIjANBgkqh...;`
- `dkim.currentValues` (array<string>, required): TXT values published now.
- `dkim.matchesRequired` (boolean, required): `true` when a published value equals `requiredValue`.
- `dkim.error` (string, required, nullable): cPanel's error text, if any.
- `spf` (object, required): The SPF record.
- `spf.state` (string, required): `valid`, `valid_hostup_policy` (the record uses `include:spf.hostup.se`; keep it), `missing`, `invalid` or `unknown`.
  Allowed values: valid, valid_hostup_policy, missing, invalid, unknown
- `spf.cpanelState` (string, required): cPanel's own result, for example `INVALID`. Example: `INVALID`
- `spf.name` (string, required): Host name of the SPF TXT record. Example: `example.com`
- `spf.type` (string, required): Always `TXT`.
  Allowed values: TXT
- `spf.cpanelRequiredMechanisms` (string, required, nullable): The mechanisms cPanel expects in the SPF record. Example: `ip4:192.0.2.23 include:relay.mailchannels.net`
- `spf.currentValues` (array<string>, required): SPF values published now.
- `spf.sendingIp` (string, required, nullable): IP address the hosting server sends mail from. Example: `192.0.2.23`
- `spf.hostupPolicyDetected` (boolean, required): `true` when the one SPF record uses `include:spf.hostup.se`.
- `spf.explanation` (string, required, nullable): Why `state` differs from cPanel's own result. `null` otherwise.
- `spf.error` (string, required, nullable): cPanel's error text, if any.
- `dmarc` (object, required): The DMARC record.
- `dmarc.state` (string, required): `valid`, `valid_with_cpanel_spf_warning` (the DMARC record is present; cPanel's warning comes from the SPF check), `missing`, `invalid` or `unknown`.
  Allowed values: valid, valid_with_cpanel_spf_warning, missing, invalid, unknown
- `dmarc.cpanelState` (string, required): cPanel's own result, for example `SPF_ERROR`. Example: `SPF_ERROR`
- `dmarc.name` (string, required): Host name of the DMARC TXT record. Example: `_dmarc.example.com`
- `dmarc.type` (string, required): Always `TXT`.
  Allowed values: TXT
- `dmarc.currentValue` (string, required, nullable): The DMARC value published now. Example: `v=DMARC1; p=quarantine`
- `dmarc.explanation` (string, required, nullable): Why `state` differs from cPanel's own result. `null` otherwise.
- `dmarc.error` (string, required, nullable): cPanel's error text, if any.
- `decision` (string, required): `configured`: nothing to change. `action_required`: see `nextAction`. `unavailable`: cPanel returned too little data. Try again.
  Allowed values: configured, action_required, unavailable
- `nextAction` (object, required): What to do next.
- `nextAction.code` (string, required): `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`.
  Allowed values: none, publish_dkim, generate_dkim_key, review_spf, review_dmarc, retry_later
- `nextAction.message` (string, required): The same advice in words.

### Responses

#### 200 - DKIM, SPF and DMARC as cPanel validates them.
```json
{
  "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."
  }
}
```

#### 400 - `domain` is missing or not a valid domain name.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "domain query param is required.",
  "code": "invalid_request",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliverability",
  "errors": [
    {
      "pointer": "/query/domain",
      "detail": "domain query param is required.",
      "code": "invalid_request"
    }
  ]
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - The domain is not on this hosting account (`domain_not_owned`), the API key lacks a required scope or the account is not active.
```json
{
  "type": "https://developer.hostup.se/errors/domain_not_owned",
  "title": "Domain not owned by hosting account",
  "status": 403,
  "detail": "The requested domain is not hosted on this cPanel account.",
  "code": "domain_not_owned",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliverability"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller.
```json
{
  "type": "https://developer.hostup.se/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 409 - The account is on Hostup's previous hosting platform. The records cannot be checked there through the API.
```json
{
  "type": "https://developer.hostup.se/errors/account_not_eligible_cpanel",
  "title": "Control panel action unavailable",
  "status": 409,
  "detail": "Email authentication records can only be inspected for hosting accounts on the cPanel control panel. This account uses HostUp's previous hosting platform. Contact support and we will migrate the existing account to cPanel at no extra charge; no new hosting plan is needed.",
  "code": "account_not_eligible_cpanel",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliverability"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 502 - cPanel's check could not be read right now. Try again.
```json
{
  "type": "https://developer.hostup.se/errors/upstream_failed",
  "title": "Upstream request failed",
  "status": 502,
  "detail": "Unable to read the domain's email authentication records from cPanel right now.",
  "code": "upstream_failed",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/email-deliverability"
}
```
