Diagnose e-mail sending
const url = 'https://api.getsitecontrol.com/v1/sites/1/emails/diagnostics';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.getsitecontrol.com/v1/sites/1/emails/diagnostics \ --header 'Authorization: Bearer <token>'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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”A broadcast id from list_broadcasts
A broadcast id from list_broadcasts
An automation id from list_automations
An automation id from list_automations
Responses
Section titled “Responses”object
Whether the site can send: blocking when a check blocks, unknown when account, sending or balance could not be read, warning when a check warns or plan or delivery could not be read
Always the five checks, in the order sending is gated
object
Ok, warning, blocking or unknown
Why, a stable code; null when ok
What to do; none when ok
Who can fix it; none when ok
What was checked
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: bounce_rate, complaint_rate, unsubscribe_rate, fractions of all e-mails the site has sent
The requested broadcast: what holds it; null when none asked
object
Ok, warning, blocking or unknown
Why, a stable code; null when ok
What to do; none when ok
Who can fix it; none when ok
As get_broadcast shows it
As get_broadcast shows it
What to do once the cause is fixed
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
The requested automation: what holds it; null when none asked
object
Ok, warning, blocking or unknown
Why, a stable code; null when ok
What to do; none when ok
Who can fix it; none when ok
The automation has an e-mail step; without one only the account and the plan apply
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
What to do once the cause is fixed
history_since: the date turn-offs are recorded from, with off_reason: unknown
{ "state": "ok", "checks": [ { "state": "ok", "reason": "account_suspended", "next_action": "none", "who": "user", "check": "account" } ], "broadcast": { "state": "ok", "reason": "account_suspended", "next_action": "none", "who": "user", "then": "resume_broadcast" }, "automation": { "state": "ok", "reason": "account_suspended", "next_action": "none", "who": "user", "then": "resume_broadcast" }}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
site_not_found: no such site in your account; broadcast_not_found, automation_not_found: the site has no such broadcast or automation
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
validation_failed: both broadcast_id and automation_id are given, or an id is invalid
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds