Skip to content

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.

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.upsert returns status: "draft" or liveVersion: null, or a send approval is still pending, expired, or superseded (sendApprovals.get). Activate it and have an approver approve it (Sending).
  • The event name does not match. The trigger’s event and the name passed to events.track differ. 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.track answered not_found. Call customers.upsert first.
  • 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.

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.

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).
  • bounced or complained: the address is usually suppressed now, and later sends to it are skipped.
  • soft_bounced or delayed: the recipient’s server deferred it; the provider keeps trying.
  • null: no delivery event has arrived yet.

See Errors and limits for each error code and what to do about it. Two come up often while setting up:

  • forbidden on apiKeys_create or projects_create from an assistant: these take a signed-in dashboard session, never an API key.
  • sender_not_verified on workflows_activate: a from domain is not verified yet.