Build with AI

Add Koltrix email sending to my app.

Before you write anything, read the Koltrix documentation: https://docs.koltrix.com/llms-full.txt (the whole docs as one Markdown file; https://docs.koltrix.com/llms.txt is the index, and any docs page is also available as Markdown by adding .md to its URL). Do not guess API fields or behaviour: if the docs don't say it, treat it as unsupported.

First ask me which language and framework this project uses, which events should send an email, and which From address to use. Then look through my codebase and follow its conventions (HTTP client, config, error handling, test runner).

Requirements:

1. API key. Read it from the environment variable KOLTRIX_API_KEY. Never hardcode it, never log it, never commit it. If the variable is missing, tell me to create a key in Koltrix under Settings → API keys (it is shown only once, and the default scopes read and send are enough) and put it in my secret store or .env file. Add only a placeholder line to .env.example.
2. Send with POST https://api.koltrix.com/api/v2/emails, with the headers Authorization: Bearer $KOLTRIX_API_KEY and Content-Type: application/json. The body has from, to (always a JSON array, even for one recipient), subject, and body_html and/or body_text; cc and bcc are optional arrays. There is no reply_to, attachments, templates or scheduled send on this endpoint, and unknown fields are silently ignored, so do not use them. The success response is 202 with {"id", "status": "queued", ...}.
3. The from address must be an exact address that is added under Settings → Domains & addresses on a domain that is verified in my workspace. Any other From address is refused with 403. If I have no verified domain yet, stop and point me to https://docs.koltrix.com/domains.md.
4. Send an Idempotency-Key header on every send: one stable key per logical email (for example "order-1042-receipt"), reused on every retry. Never generate a new key inside the retry loop. Keys are remembered for 24 hours. A retry after the first request finished returns 200 with the original body and the header Idempotent-Replayed: true.
5. Handle errors by HTTP status. 400, 401, 403 and 404: do not retry, fix the request, key or data. 409 and 503: retry shortly with the same Idempotency-Key. 500: retry with exponential backoff and the same key. 429 means two different things, so look at the code field: without a code it is the rate limit (60 requests per minute per API key), so wait the Retry-After seconds and retry; with "code": "quota_exceeded" it is the plan's send quota, so do NOT retry until resets_at and surface it to a person.
6. Limits to respect: 60 requests per minute per API key. Every recipient (to, cc and bcc) counts against the plan's send quota, and trial workspaces have tighter caps; the numbers are in https://docs.koltrix.com/limits.md.
7. If I want delivery events, add a webhook handler that verifies the X-Koltrix-Signature header (see https://docs.koltrix.com/webhooks.md): sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the endpoint's signing secret from an environment variable, compared in constant time.
8. Write tests that mock the HTTP call. Check the URL, that the Authorization header comes from KOLTRIX_API_KEY, that the Idempotency-Key is present and is the same on a retry, the body shape, and both 429 branches (rate limit versus quota_exceeded). Never call the real API from tests: Koltrix has no test mode, so every request is real.
9. Finish by telling me how to run it, and offer to send one real email to an address I choose.

Set up my domain's DNS for Koltrix.

Read https://docs.koltrix.com/domains.md first. Do not invent any record value: the ownership token and the DKIM public key are different for every domain, so the exact values come from Koltrix. Ask me to open Settings → Domains & addresses in Koltrix, click Add domain, enter my domain, and paste the five records it shows (type, name and value) here. If Koltrix offers "Set up automatically" (Domain Connect) or "Connect Cloudflare" for my provider, tell me that is the easiest route and walk me through it instead.

The five records, so you can check what I paste:
1. Ownership: TXT at _koltrix, value koltrix-verify=<token from Koltrix>.
2. MX at @ pointing to mail.koltrix.com, priority 10. This moves my incoming mail to Koltrix, so remove other MX records for the domain only when I am ready to switch, and warn me first.
3. SPF: TXT at @. A domain may have only ONE SPF record. If it has none, the value is v=spf1 include:_spf.koltrix.com -all. If it already has one, merge include:_spf.koltrix.com into it (Koltrix shows a merged value) instead of adding a second record.
4. DKIM: TXT at kx1._domainkey, value v=DKIM1; k=rsa; p=<key from Koltrix>.
5. DMARC: TXT at _dmarc, value v=DMARC1; p=quarantine (an existing DMARC record that already works stays as it is).

Steps:
1. Ask which provider hosts my DNS (Cloudflare, GoDaddy, Namecheap, Route 53 or other) and give me exact steps for it.
2. Before changing anything, look at what exists with dig, and show me the output: dig +short TXT example.com, dig +short MX example.com, dig +short TXT _dmarc.example.com (replace example.com with my domain).
3. Confirm each record with me before I publish it. Do not change my DNS yourself unless I explicitly tell you to.
4. After I publish them, verify with dig and compare with what Koltrix shows: dig +short TXT _koltrix.example.com, dig +short MX example.com, dig +short TXT example.com, dig +short TXT kx1._domainkey.example.com, dig +short TXT _dmarc.example.com.
5. Tell me to click "Check again" in Koltrix. DNS usually takes a few minutes and sometimes a few hours; the domain becomes verified when all five records check out.
6. Then have me click Add address on the domain and add the exact mailbox I will send from, for example [email protected]. The API only sends from addresses added this way.

If you need more detail than https://docs.koltrix.com/domains.md gives, everything is also in https://docs.koltrix.com/llms-full.txt.

Receive and verify Koltrix webhooks in my app.

Before you write anything, read the Koltrix documentation: https://docs.koltrix.com/llms-full.txt (the whole docs as one Markdown file; https://docs.koltrix.com/llms.txt is the index, and any docs page is also available as Markdown by adding .md to its URL). Do not guess API fields or behaviour: if the docs don't say it, treat it as unsupported. The page to follow is https://docs.koltrix.com/webhooks.md.

First ask me which language and framework this project uses, and which public HTTPS URL the handler will have. Then add a handler at that route.

Requirements:
1. Koltrix sends each event as a POST with a JSON body and the headers X-Koltrix-Event and X-Koltrix-Signature. The events that are sent today are message.sent, message.bounced, message.opened and message.clicked. Do not rely on message.delivered, message.complained or message.unsubscribed: they are reserved and not sent yet.
2. Verify the signature before doing anything else. X-Koltrix-Signature is "sha256=" followed by the hex HMAC-SHA256 of the raw request body, keyed with the endpoint's signing secret (it starts with whsec_). Hash the exact bytes that arrived: never parse and re-serialise the JSON first, and in frameworks that parse JSON by default, capture the raw body. Compare in constant time and answer 401 on a mismatch.
3. Read the signing secret from an environment variable, for example KOLTRIX_WEBHOOK_SECRET. Never hardcode it or log it. Settings → Webhooks does not show the secret yet, so I may need to email [email protected] for it; tell me that if I don't have it.
4. The timestamp field (Unix seconds) is inside the signed body: reject events more than a few minutes old.
5. Koltrix waits up to 8 seconds for an answer and each event is attempted once: a timeout or non-2xx answer is recorded and not retried. Answer 200 quickly and do slow work afterwards. Make processing idempotent (for example remember message_id plus event), and ignore events with "test": true in production.
6. Events can arrive out of order, and an open can arrive before the matching message.sent. message.sent and message.bounced don't include the recipient; look it up with GET /api/v2/messages/:id if needed, and reconcile with GET /api/v2/messages periodically if missing an event matters.
7. Write a test that signs a sample payload with a test secret and checks that a valid signature passes, a modified body fails, and a stale timestamp is rejected.
8. Tell me how to add the endpoint in Koltrix (Settings → Webhooks, paste the https:// URL and click Add).

Migrate my email sending from SendGrid, Resend, Postmark or Amazon SES to Koltrix.

Before you write anything, read the Koltrix documentation: https://docs.koltrix.com/llms-full.txt (the whole docs as one Markdown file; https://docs.koltrix.com/llms.txt is the index, and any docs page is also available as Markdown by adding .md to its URL). Do not guess API fields or behaviour: if the docs don't say it, treat it as unsupported.

First ask me which provider I use today. Then search my codebase for every place that sends email or handles the provider's webhooks (SDK imports, API calls, SMTP settings, environment variable names) and list them for me before you change anything.

Koltrix facts you must respect:
1. Sending is POST https://api.koltrix.com/api/v2/emails with Authorization: Bearer $KOLTRIX_API_KEY. The body fields are from, to (array), cc, bcc, subject, body_html and body_text. Nothing else is read.
2. Not supported on that endpoint: reply_to, attachments, custom headers, templates, scheduled sends, categories, tags or metadata, and merge variables (the body is sent exactly as written). Koltrix has no official SDKs; it is plain HTTPS. For each feature my current code uses that Koltrix lacks, tell me and ask what to do before you drop or work around it. If I only need SMTP, the SMTP relay is an alternative (https://docs.koltrix.com/smtp-relay.md), but it does not parse multipart messages or attachments.
3. Each request is one message to one set of recipients. For per-recipient personalisation, build each message in my app and make one API call per recipient.
4. Add an Idempotency-Key to every send (one stable key per logical email, reused on retries). Error handling: 429 without a code is the rate limit (60 requests per minute per key; wait Retry-After); 429 with "code": "quota_exceeded" is the plan quota (do not retry until resets_at); 409, 500 and 503 are retried with the same key; 400, 401, 403 and 404 are not retried.
5. The From address must be an address on a verified domain that is added in Koltrix. Setting up the domain means five DNS records; do not duplicate my existing SPF record, merge into it (https://docs.koltrix.com/domains.md). Pointing MX at Koltrix moves incoming mail, so ask me before touching MX.
6. Webhooks: the events are message.sent, message.bounced, message.opened and message.clicked, signed with X-Koltrix-Signature (https://docs.koltrix.com/webhooks.md). Map my provider's events onto these and tell me which ones have no equivalent. Events are attempted once, with no retries.
7. Read the key from the environment variable KOLTRIX_API_KEY; never hardcode it. Keep the old provider's code behind a switch or a feature flag until a real test email has arrived, then remove it.
8. Write tests with the HTTP call mocked. Koltrix has no test mode, so never call the real API from tests.
9. Finish with a checklist of what I still have to do by hand: verify the domain, create the API key, add the webhook endpoint and switch traffic.

Connect Koltrix to my AI assistant with MCP.

Read https://docs.koltrix.com/mcp.md first. The server URL is https://mcp.koltrix.com/mcp and it uses OAuth sign-in with my Koltrix account. There is no API key for MCP, so do not ask me for one and never put an API key anywhere.

Ask me which app I use, then give me only the steps for that app:
1. Claude (claude.ai or Claude Desktop): Settings → Connectors → Add custom connector, name it Koltrix, paste https://mcp.koltrix.com/mcp, click Connect, then sign in to Koltrix, choose the workspace and click Approve.
2. Claude Code: run claude mcp add --transport http koltrix https://mcp.koltrix.com/mcp (add --scope user to make it available in every project), then run /mcp inside Claude Code, choose koltrix and authenticate. The OAuth step opens my browser, so I have to do that part.
3. ChatGPT: Settings → Apps & Connectors (turn on Developer mode under Advanced settings if my plan needs it), create a custom connector named Koltrix, paste https://mcp.koltrix.com/mcp and choose OAuth. Menu names vary between plans.
4. Cursor: add {"mcpServers": {"koltrix": {"url": "https://mcp.koltrix.com/mcp"}}} to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project), then sign in when Cursor asks.

If you can run shell commands and I use Claude Code, run the command in step 2 for me. Afterwards explain what the connection can do: read, search, organise (labels, archive, read and starred state) and draft mail in my Koltrix inbox. Sending is off by default: a workspace owner or admin has to allow it, I have to opt in when I connect, and the assistant must show me the message and get my explicit yes for each send. No assistant can forward or permanently delete mail.

Everything about MCP is on https://docs.koltrix.com/mcp.md, and the whole documentation is in https://docs.koltrix.com/llms-full.txt.

## Koltrix (email API)

Koltrix docs for AI: before writing or changing any Koltrix code, read https://docs.koltrix.com/llms-full.txt (the whole documentation as one Markdown file). The index is https://docs.koltrix.com/llms.txt, and any docs page is also available as Markdown by adding .md to its URL, for example https://docs.koltrix.com/sending-email.md. Do not guess fields: if the docs don't say it, it isn't supported.

- Send with POST https://api.koltrix.com/api/v2/emails and the header Authorization: Bearer <key>. The key lives in the environment variable KOLTRIX_API_KEY. Never hardcode it, log it or commit it.
- Always send an Idempotency-Key header: one stable key per logical email, reused on every retry.
- The from address must be an active address on a verified domain (Settings → Domains & addresses), or the API answers 403.
- The send endpoint has no reply_to, attachments, templates or scheduled send. Don't assume another provider's fields.
- 429 without a code field is the rate limit (60 requests per minute per key): wait Retry-After. 429 with "code": "quota_exceeded" is the plan's send quota: don't retry, tell a person.
- Verify webhooks: X-Koltrix-Signature is sha256= plus the hex HMAC-SHA256 of the raw body; compare in constant time.
- There is no test mode. Tests must mock HTTP and never call the real API.
- To let an assistant read, organise and draft mail in Koltrix, use MCP: https://mcp.koltrix.com/mcp