Troubleshooting

The problems people run into most, what causes them and what to do. For a specific error message, Errors lists every one.

Email isn't arriving#

Work through these in order.

1. Find the message. Open Settings → Logs, or call GET /api/v2/messages?recipient=<address>.
   • Not there at all: the send was refused. Check the HTTP response or SMTP reply your code got.
   • queued for more than a minute: email [email protected] with the message id. The queue is normally empty within a second.
   • bounced: the error field has the receiving server's reason. A typo in the address, or a mailbox that doesn't exist, is the usual cause.
   • sent: Koltrix handed it off. Carry on below.
2. Check spam at the recipient. If it's there, the message was delivered but not trusted.
3. Check the domain under Settings → Domains & addresses. Every record should be verified, DKIM above all; unsigned mail goes to spam.
4. Check the suppression list. If the address is under Settings → Blocked senders → We won't email these, Koltrix skips it on purpose. See Deliverability.
5. Score a message at mail-tester.com. Anything under 8 out of 10 points to something it will name.

"from address … is not registered for this account" (403)#

The From address isn't an active address in your workspace. Koltrix only sends from addresses you have added, even on a verified domain.

• If the message says the domain is verified: open the domain under Settings → Domains & addresses, click Add address and add the exact address you send from.
• Otherwise: verify the domain first, then add the address.

Display names are fine: Acme <[email protected]> only needs [email protected] added.

"invalid or revoked api key" (401)#

• Did you copy the whole key, including kx_?
• Is the header Authorization: Bearer kx_…, with Bearer and a space?
• Was the key revoked in Settings → API keys? Revoked keys are refused immediately. Create a new one.

"missing permission: …" (403)#

The key works but lacks the scope this endpoint needs. Scopes can't be changed after a key is created: create a key with the right scopes, deploy it, then revoke the old one. Which scope each endpoint needs.

429 Too Many Requests#

Look at the body.

• No code field: the rate limit of 60 requests per minute per API key. Wait Retry-After seconds. Sending to many recipients? Put them in one request or use fewer, larger batches.
• "code": "quota_exceeded": your plan's send quota is used up until resets_at. Retrying won't help; upgrade or wait. See Limits and quotas.

400 invalid body on a send#

The JSON didn't parse into the expected fields. Most often to was sent as a string; it must be an array: "to": ["[email protected]"]. Also check the Content-Type: application/json header.

404 straight after sending#

GET /api/v2/messages/:id answers 404 while the message is still queued, usually for under a second. Poll again, or use webhooks.

Domain won't verify#

Settings shows what it found for each record. Common causes (the records are explained in Custom domains and DNS):

• Not long enough. DNS can take minutes to hours. Press Check again every few minutes.
• The name is doubled. If the saved record reads kx1._domainkey.example.com.example.com, your provider added the domain for you. Use the short name: kx1._domainkey, _koltrix, _dmarc, or @ for the domain itself.
• Two SPF records. A domain may have only one. Replace your existing SPF record with the merged one Koltrix shows; don't add a second.
• The DKIM value is damaged. A long value split into quoted pieces is fine; a missing character, an added space or a line break is not. Paste it with the copy button in one go. Route 53 needs you to split it yourself: "first 255 characters" "the rest".
• Claimed elsewhere. The domain is verified in another workspace. See If the domain is claimed by another workspace.

dnschecker.org shows whether a record has reached DNS servers around the world.

Webhook not arriving#

1. Is the endpoint listed under Settings → Webhooks, with an https:// URL?
2. Does the event fire? Koltrix sends message.sent, message.bounced, message.opened and message.clicked. Clicks aren't tracked on API or SMTP sends, and SMTP relay sends have no open tracking, so those events don't come for them. See Webhooks.
3. Did your server answer 2xx within 8 seconds? Koltrix tries each event once and doesn't retry, so a slow or failing handler loses the event. Answer first, then do the work.
4. Is your server rejecting the signature? See below.

Webhook signature doesn't verify#

Almost always one of these:

• Hashing parsed JSON instead of the raw body. Your framework parsed the body before your handler saw it. Use the raw bytes (in Express, express.raw({ type: "application/json" })).
• Changing the body, for example trimming whitespace, before hashing it.
• The wrong secret. Each endpoint has its own whsec_… secret.

Working examples are in Webhooks.

SMTP relay problems#

More in SMTP relay.

AI assistant problems#

See AI assistants → Troubleshooting.

Still stuck#

Email [email protected] with what you tried, what you expected and what happened, the message id if it's about a send, and roughly when it happened. We answer within one business day.