---
title: "Get domain health"
method: GET
path: "/domains/{id}/health"
tags: ["Domains"]
---

# Get domain health

`GET /domains/{id}/health`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/domains/{id}/health`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Return a domain's health in one read. `dns` and `blocklist` are the stored results of the check Shipmail runs every 6 hours: whether the MX, SPF, DKIM and DMARC records pass, and whether the Spamhaus Domain Block List (DBL) lists the domain. This endpoint does not run a new DNS check; use `GET /domains/{id}/dns-records` for a live one. `delivery` covers the recipients of messages sent from the domain's mailboxes that the API key can see, in the last 30 days, in total and split by recipient provider.

## Headers

- `X-Shipmail-Organization` string

## Response `200`

The domain's stored DNS and blocklist state and its last 30 days of delivery.

- DomainHealth
  - `object` 'domain_health', required
  - `domain_id` string, required
  - `domain` string, required: Domain name.
  - `generated_at` string, date-time, required
  - `dns` object, required: Stored results of the DNS check that runs every 6 hours.
    - `mx` boolean, required
    - `spf` boolean, required
    - `dkim` boolean, required
    - `dmarc` boolean, required
    - `last_checked_at` string, date-time, nullable, required: When the stored DNS check last ran. Null if it has not run yet.
  - `blocklist` object, required: Stored Spamhaus DBL state from the same check that runs every 6 hours.
    - `list` 'spamhaus_dbl', required
    - `listed` boolean, required
    - `listed_since` string, date-time, nullable, required: When the check first found the domain listed. Null when it is not listed.
  - `delivery` object, required: Recipients of messages sent from the domain's mailboxes that the API key can see, in the last 30 days.
    - `since` string, date-time, required
    - `until` string, date-time, required
    - `recipients` integer, required: All recipients in the period.
    - `delivered` integer, required: Recipients the receiving server accepted.
    - `bounced` integer, required: Recipients that bounced.
    - `deferred` integer, required: Recipients the receiving server temporarily refused.
    - `complained` integer, required: Recipients who marked the message as spam.
    - `failed` integer, required: Recipients Shipmail could not send to.
    - `suppressed` integer, required: Recipients skipped because they are on a suppression list.
    - `queued` integer, required: Recipients still waiting to be sent.
    - `sent` integer, required: Recipients sent with no delivery result yet.
    - `delivery_rate` number, nullable, required: Percentage of recipients with a final outcome that were delivered, from 0 to 100, rounded to one decimal. Delivered and complained count as delivered; bounced, deferred and failed do not. Null when no recipient has a final outcome yet.
    - `providers` DomainHealthProviderDelivery[], required: One entry per recipient provider with at least one recipient in the period.
      - `provider` 'google' | 'microsoft' | 'yahoo' | 'apple' | 'other', required: Recipient mail provider, read from the recipient address: google is Gmail, microsoft is Outlook and Hotmail, yahoo is Yahoo and AOL, apple is iCloud. Business domains hosted by Google Workspace or Microsoft 365 count as other.
      - `recipients` integer, required: Recipients at this provider.
      - `delivered` integer, required: Recipients the receiving server accepted.
      - `bounced` integer, required: Recipients that bounced.
      - `deferred` integer, required: Recipients the receiving server temporarily refused.
      - `complained` integer, required: Recipients who marked the message as spam.
      - `delivery_rate` number, nullable, required: Percentage of recipients with a final outcome that were delivered, from 0 to 100, rounded to one decimal. Delivered and complained count as delivered; bounced, deferred and failed do not. Null when no recipient has a final outcome yet.

## Other responses

- `404`: Resource not found.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)