---
title: "Diagnose e-mail sending"
method: GET
path: "/v1/sites/{site_id}/emails/diagnostics"
tags: ["Emails"]
---

# Diagnose e-mail sending

`GET /v1/sites/{site_id}/emails/diagnostics`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/emails/diagnostics`
- Auth: HTTP bearer

Why the site's e-mail does not go out, or goes out slowly: the first call for
"my broadcast is stuck", "nothing is sent", "sending is paused" or "why can't
I start it". Five checks in the order sending is gated - the account, sending
being enabled, the email balance, the plan, delivery - each with a stable
`reason` code, what to do (`next_action`), who can do it (`who`) and facts in
`values`. Read `who` before promising anything: what `support` decides is
never promised. Name a broadcast or an automation to learn what holds it and
what to do after the fix (`then`); nothing resumes or turns on by itself.

The answer is the stored state and makes no change; the balance carries its
`updated_at`. Recipients and credits a broadcast needs are
`get_broadcast_recipients`, its sender address `get_broadcast`, domain
verification `list_email_domains`. The meaning of every code and how to word
it for the user: the guide `emails.sending`.

## Path parameters

- `site_id` integer, required

## Query parameters

- `broadcast_id` integer: A broadcast id from `list_broadcasts`
- `automation_id` integer: An automation id from `list_automations`

## Response `200`

Successful Response

- EmailSendingDiagnosis
  - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing holds it. warning: it works, with a limit or a risk the user should know about. blocking: it does not send until the cause is fixed. unknown: the source could not be read now; ask again later.
  - `checks` EmailDiagnosticCheck[], required: Always the five checks, in the order sending is gated
    - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing holds it. warning: it works, with a limit or a risk the user should know about. blocking: it does not send until the cause is fixed. unknown: the source could not be read now; ask again later.
    - `reason` 'account_suspended' | 'trial_ended' | 'plan_not_selected' | 'subscription_ended' | 'site_deactivated' | 'email_not_verified' | 'limited' | 'blocked_suspicious_activity' | 'blocked_poor_delivery' | 'sandbox' | 'other' | 'overdraft' | 'empty' | 'broadcasts_not_on_plan' | 'automations_not_on_plan' | 'high_complaints' | 'high_bounces' | 'contact_validation': `account_suspended`: The account is suspended or paused by our team, or has no plan; nothing is sent. Only support can lift it. `trial_ended`: The trial is over; broadcasts and automations do not send until the owner chooses a plan. `plan_not_selected`: No plan was chosen after installing the Shopify app; nothing is sent until the owner chooses one. `subscription_ended`: The subscription has ended or is unpaid; nothing is sent until the owner sorts out billing. `site_deactivated`: The site is turned off, by a user or because the plan allows fewer sites; nothing is sent from it until the owner turns it back on. `email_not_verified`: This user has not confirmed their e-mail address: they cannot start broadcasts or turn on automations; running sends go on. `limited`: Sending speed is limited for now: everything is sent, large sends take longer. Support decides when the limit is lifted. `blocked_suspicious_activity`: Sending is blocked by our automatic check for suspicious activity. If the user believes it is a mistake, they contact support. `blocked_poor_delivery`: Sending is stopped: too many recipients bounced or complained. The user cleans the contact list, then contacts support. `sandbox`: With `has_sent: false`, sending is not enabled for the site yet; with `has_sent: true`, it is paused pending a review. Either way the user writes to support where the contacts come from and what they plan to send; the review starts after that message. `other`: Sending is turned off for this site; the user contacts support. `overdraft`: The e-mail balance is used up: broadcasts are paused and new ones cannot start. Automations keep sending on credit for now and will be turned off soon. The owner tops up the balance. `empty`: The e-mail balance is used up: broadcasts are paused and automations are turned off. The owner tops up the balance. `broadcasts_not_on_plan`: The plan does not include broadcasts; the owner upgrades it. `automations_not_on_plan`: The plan does not include automations; the owner upgrades it. `high_complaints`: Many recipients mark the e-mails as spam; sending goes on, but the user should clean the contact list and check what they send. `high_bounces`: Many addresses bounce; sending goes on, but the user should clean the contact list. `contact_validation`: Anti-Bounce checks contacts before sending; each check uses credits of the e-mail balance.
    - `next_action` 'none' | 'contact_support' | 'top_up_balance' | 'upgrade_plan' | 'check_billing' | 'activate_site' | 'verify_email' | 'clean_contacts' | 'wait', required: none: nothing to do. contact_support: write to support. top_up_balance: buy e-mail credits. upgrade_plan: choose a plan that has it. check_billing: sort out the subscription's payment. activate_site: turn the site back on. verify_email: confirm the user's e-mail address from the message we sent. clean_contacts: remove addresses that bounce or complain. wait: nothing to do but wait.
    - `who` 'user' | 'owner' | 'support' | 'none', required: user: an editor of the site fixes it. owner: the account owner, for money, the plan and turning sites on. support: a person on our side decides; never promise the outcome. none: nobody needs to act.
    - `check` 'account' | 'sending' | 'balance' | 'plan' | 'delivery', required: account: the account, the plan's state and the site being on, and the calling user's confirmed e-mail. sending: whether sending is enabled for the site. balance: the account's e-mail balance. plan: whether the plan includes broadcasts and automations. delivery: bounces and complaints.
    - `values` object, required: Facts of the check, `{}` when none. sending: `has_sent`, whether the site has ever sent. balance: `status` (enabled, warning, disabled), `updated_at` of the stored balance, and `credits` left, only with the `emails.full` right. delivery: `reputation`, the sender reputation the admin shows (poor, fair, good, excellent), and `bounce_level`, `complaint_level`, the same levels of the two metrics that lower it; `bounce_rate`, `complaint_rate`, `unsubscribe_rate`, fractions of all e-mails the site has sent. The check's `state` can be ok while `reputation` is fair or poor
  - `broadcast` BroadcastDiagnosis
    - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing holds it. warning: it works, with a limit or a risk the user should know about. blocking: it does not send until the cause is fixed. unknown: the source could not be read now; ask again later.
    - `reason` 'account_suspended' | 'trial_ended' | 'plan_not_selected' | 'subscription_ended' | 'site_deactivated' | 'email_not_verified' | 'limited' | 'blocked_suspicious_activity' | 'blocked_poor_delivery' | 'sandbox' | 'other' | 'overdraft' | 'empty' | 'broadcasts_not_on_plan' | 'automations_not_on_plan' | 'high_complaints' | 'high_bounces' | 'contact_validation': `account_suspended`: The account is suspended or paused by our team, or has no plan; nothing is sent. Only support can lift it. `trial_ended`: The trial is over; broadcasts and automations do not send until the owner chooses a plan. `plan_not_selected`: No plan was chosen after installing the Shopify app; nothing is sent until the owner chooses one. `subscription_ended`: The subscription has ended or is unpaid; nothing is sent until the owner sorts out billing. `site_deactivated`: The site is turned off, by a user or because the plan allows fewer sites; nothing is sent from it until the owner turns it back on. `email_not_verified`: This user has not confirmed their e-mail address: they cannot start broadcasts or turn on automations; running sends go on. `limited`: Sending speed is limited for now: everything is sent, large sends take longer. Support decides when the limit is lifted. `blocked_suspicious_activity`: Sending is blocked by our automatic check for suspicious activity. If the user believes it is a mistake, they contact support. `blocked_poor_delivery`: Sending is stopped: too many recipients bounced or complained. The user cleans the contact list, then contacts support. `sandbox`: With `has_sent: false`, sending is not enabled for the site yet; with `has_sent: true`, it is paused pending a review. Either way the user writes to support where the contacts come from and what they plan to send; the review starts after that message. `other`: Sending is turned off for this site; the user contacts support. `overdraft`: The e-mail balance is used up: broadcasts are paused and new ones cannot start. Automations keep sending on credit for now and will be turned off soon. The owner tops up the balance. `empty`: The e-mail balance is used up: broadcasts are paused and automations are turned off. The owner tops up the balance. `broadcasts_not_on_plan`: The plan does not include broadcasts; the owner upgrades it. `automations_not_on_plan`: The plan does not include automations; the owner upgrades it. `high_complaints`: Many recipients mark the e-mails as spam; sending goes on, but the user should clean the contact list and check what they send. `high_bounces`: Many addresses bounce; sending goes on, but the user should clean the contact list. `contact_validation`: Anti-Bounce checks contacts before sending; each check uses credits of the e-mail balance.
    - `next_action` 'none' | 'contact_support' | 'top_up_balance' | 'upgrade_plan' | 'check_billing' | 'activate_site' | 'verify_email' | 'clean_contacts' | 'wait', required: none: nothing to do. contact_support: write to support. top_up_balance: buy e-mail credits. upgrade_plan: choose a plan that has it. check_billing: sort out the subscription's payment. activate_site: turn the site back on. verify_email: confirm the user's e-mail address from the message we sent. clean_contacts: remove addresses that bounce or complain. wait: nothing to do but wait.
    - `who` 'user' | 'owner' | 'support' | 'none', required: user: an editor of the site fixes it. owner: the account owner, for money, the plan and turning sites on. support: a person on our side decides; never promise the outcome. none: nobody needs to act.
    - `id` integer, required
    - `status` string, nullable: As `get_broadcast` shows it
    - `status_reason` string, nullable: As `get_broadcast` shows it
    - `then` 'resume_broadcast' | 'duplicate_broadcast' | 'turn_on_automation' | 'none', required: `resume_broadcast`: After the cause is fixed, the user presses Resume on the broadcast; it does not resume by itself. `duplicate_broadcast`: A stop is final: after the cause is fixed, the user sends it to those who did not get it with Resend > Resend to non-recipients. `turn_on_automation`: After the cause is fixed, the user turns the automation back on; it does not turn on by itself. `none`: Nothing to do after the fix.
    - `values` object, required: `stops_at`: when a paused broadcast is stopped for good. `ended_at`: when an ended one ended. `history_since`: the date status reasons are recorded from, for an older broadcast
  - `automation` AutomationDiagnosis
    - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing holds it. warning: it works, with a limit or a risk the user should know about. blocking: it does not send until the cause is fixed. unknown: the source could not be read now; ask again later.
    - `reason` 'account_suspended' | 'trial_ended' | 'plan_not_selected' | 'subscription_ended' | 'site_deactivated' | 'email_not_verified' | 'limited' | 'blocked_suspicious_activity' | 'blocked_poor_delivery' | 'sandbox' | 'other' | 'overdraft' | 'empty' | 'broadcasts_not_on_plan' | 'automations_not_on_plan' | 'high_complaints' | 'high_bounces' | 'contact_validation': `account_suspended`: The account is suspended or paused by our team, or has no plan; nothing is sent. Only support can lift it. `trial_ended`: The trial is over; broadcasts and automations do not send until the owner chooses a plan. `plan_not_selected`: No plan was chosen after installing the Shopify app; nothing is sent until the owner chooses one. `subscription_ended`: The subscription has ended or is unpaid; nothing is sent until the owner sorts out billing. `site_deactivated`: The site is turned off, by a user or because the plan allows fewer sites; nothing is sent from it until the owner turns it back on. `email_not_verified`: This user has not confirmed their e-mail address: they cannot start broadcasts or turn on automations; running sends go on. `limited`: Sending speed is limited for now: everything is sent, large sends take longer. Support decides when the limit is lifted. `blocked_suspicious_activity`: Sending is blocked by our automatic check for suspicious activity. If the user believes it is a mistake, they contact support. `blocked_poor_delivery`: Sending is stopped: too many recipients bounced or complained. The user cleans the contact list, then contacts support. `sandbox`: With `has_sent: false`, sending is not enabled for the site yet; with `has_sent: true`, it is paused pending a review. Either way the user writes to support where the contacts come from and what they plan to send; the review starts after that message. `other`: Sending is turned off for this site; the user contacts support. `overdraft`: The e-mail balance is used up: broadcasts are paused and new ones cannot start. Automations keep sending on credit for now and will be turned off soon. The owner tops up the balance. `empty`: The e-mail balance is used up: broadcasts are paused and automations are turned off. The owner tops up the balance. `broadcasts_not_on_plan`: The plan does not include broadcasts; the owner upgrades it. `automations_not_on_plan`: The plan does not include automations; the owner upgrades it. `high_complaints`: Many recipients mark the e-mails as spam; sending goes on, but the user should clean the contact list and check what they send. `high_bounces`: Many addresses bounce; sending goes on, but the user should clean the contact list. `contact_validation`: Anti-Bounce checks contacts before sending; each check uses credits of the e-mail balance.
    - `next_action` 'none' | 'contact_support' | 'top_up_balance' | 'upgrade_plan' | 'check_billing' | 'activate_site' | 'verify_email' | 'clean_contacts' | 'wait', required: none: nothing to do. contact_support: write to support. top_up_balance: buy e-mail credits. upgrade_plan: choose a plan that has it. check_billing: sort out the subscription's payment. activate_site: turn the site back on. verify_email: confirm the user's e-mail address from the message we sent. clean_contacts: remove addresses that bounce or complain. wait: nothing to do but wait.
    - `who` 'user' | 'owner' | 'support' | 'none', required: user: an editor of the site fixes it. owner: the account owner, for money, the plan and turning sites on. support: a person on our side decides; never promise the outcome. none: nobody needs to act.
    - `id` integer, required
    - `is_active` boolean, required
    - `sends_email` boolean, required: The automation has an e-mail step; without one only the account and the plan apply
    - `off_reason` string, nullable: Why it was turned off, a reason of `list_automation_history`; null when it is on or a person turned it off; `unknown` when it is off and no record says why
    - `then` 'resume_broadcast' | 'duplicate_broadcast' | 'turn_on_automation' | 'none', required: `resume_broadcast`: After the cause is fixed, the user presses Resume on the broadcast; it does not resume by itself. `duplicate_broadcast`: A stop is final: after the cause is fixed, the user sends it to those who did not get it with Resend > Resend to non-recipients. `turn_on_automation`: After the cause is fixed, the user turns the automation back on; it does not turn on by itself. `none`: Nothing to do after the fix.
    - `values` object, required: `history_since`: the date turn-offs are recorded from, with `off_reason: unknown`

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `site_not_found`: no such site in your account; `broadcast_not_found`, `automation_not_found`: the site has no such broadcast or automation
- `422`: `validation_failed`: both `broadcast_id` and `automation_id` are given, or an id is invalid
- `429`: Rate limited
- `503`: Temporarily unavailable; retry later

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)