Troubleshooting
Most questions come down to one: why did this customer not get the email? Customer.lite records the answer. Ask your assistant to look it up with messages_list and messages_get, or work through the checks below.
No message at all
Section titled “No message at all”messages.list for the customer shows no message from the workflow: the run never started, or has not reached its send step. A run without a message cannot be read through the API yet (an API for runs and their step logs is planned), so go through these checks:
- The workflow is not live.
workflows.upsertreturnsstatus: "draft"orliveVersion: null, or a send approval is stillpending,expired, orsuperseded(sendApprovals.get). Activate it and have an approver approve it (Sending). - The event name does not match. The trigger’s
eventand thenamepassed toevents.trackdiffer. Names are compared exactly. Use the same name in both. - The event came before the workflow went live. A run starts only for events recorded while a version is live. Record a new event. Earlier events do not start runs.
- The customer already had an active run. An event that arrives during a customer’s run of the same workflow starts no second run. Let the earlier run end first.
- The customer did not exist.
events.trackanswerednot_found. Callcustomers.upsertfirst. - The run ended at a condition. A condition that did not hold ends the run before the send. Check the attribute the condition reads (
customers.get). - The run is still waiting. A delay before the send step holds the run; the message appears once the delay is over.
A message that was not sent
Section titled “A message that was not sent”The message exists, and its state says why.
| State and reason | Meaning |
|---|---|
skipped, no_address |
The customer has no email address. |
skipped, unsubscribed |
The customer unsubscribed, by link or through customers.unsubscribe. |
skipped, suppressed |
An earlier bounce or complaint suppressed the address. |
skipped, customer_missing |
The customer no longer exists. No action deletes customers yet, so this does not happen today. |
skipped, sender_not_verified |
The from domain stopped being a verified sending domain. |
skipped, workflow_stopped |
The run’s workflow was no longer active when the send came due. No action stops workflows yet, so this does not happen today. |
queued |
Waiting to be sent or retried; temporary provider errors are retried for up to a day. |
unknown |
The provider’s answer was lost. It is not resent; it resolves from delivery events, or fails after 72 hours. |
failed |
The provider refused it, or retries ran out. providerReason has the provider’s explanation. |
Sent, but not received
Section titled “Sent, but not received”The message is accepted: the provider took it. Its deliveryStatus tells what happened next.
delivered: the recipient’s mail server accepted it. Look in the spam folder, and check that the sending domain has DKIM and DMARC in place (Sending).bouncedorcomplained: the address is usually suppressed now, and later sends to it are skipped.soft_bouncedordelayed: the recipient’s server deferred it; the provider keeps trying.null: no delivery event has arrived yet.
Calls that are refused
Section titled “Calls that are refused”See Errors and limits for each error code and what to do about it. Two come up often while setting up:
forbiddenonapiKeys_createorprojects_createfrom an assistant: these take a signed-in dashboard session, never an API key.sender_not_verifiedonworkflows_activate: afromdomain is not verified yet.