Koltrix logoKoltrixDocs
Help

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.

Message still queued

GET /api/v2/messages/:id returns status: "queued" until the message has been handed to the receiving server, usually within a second or two. 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. Recent deliveries on the endpoint's row shows what each attempt got back.
  4. Is the address public? An endpoint on localhost, a private network address or a name that resolves to one is never contacted; the delivery reads "blocked: the endpoint resolves to a private or reserved address". Redirects aren't followed either: give the final URL.
  5. 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, shown in its row under Settings → Webhooks (Send test posts a signed test event).

Working examples are in Webhooks.

SMTP relay problems

SymptomCause and fix
Can't connect, or the connection times outUse smtp.koltrix.com port 2525. Ports 587 and 465 don't accept API keys.
Certificate or "TLS" errors on the relayConnect to the host name smtp.koltrix.com (not an IP address), on port 2525 with STARTTLS. The certificate is issued for that name.
535 5.7.8 Authentication failed (…)The text in brackets says why: the password isn't a kx_ key, the key is invalid or revoked, or it lacks the send scope.
501 5.5.4 Invalid FROM addressPut the address in angle brackets: MAIL FROM:<[email protected]>.
554 5.6.0 Message not acceptedThe message has an attachment, an inline image or another part the relay can't carry. Send a text or HTML body only.
421 4.7.0 Too many authentication failuresFive failed logins on one connection. Check the key (kx_…, with the send scope).
452 4.5.3Either over 1,000 recipients in one message, or your send quota is used up. The text says which.

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.