Quickstart

This guide takes you from "I just made an account" to "the recipient got my email." Allow about ten minutes — most of the wall-clock time is DNS propagation.

You'll do four things:

1. Sign up at app.koltrix.com.
2. Add and verify a sending domain (and an address on it).
3. Create an API key.
4. Send your first email with POST /api/v2/emails.

1. Sign up

Head to app.koltrix.com, create an account, and pick an organisation name. The first user on a new org is the owner. Owners can invite teammates later from Settings → Team.

2. Add a sending domain

In Settings → Domains, click Add domain and enter the apex you want to send from (e.g. acme.com). Koltrix shows you the DNS records to publish at your registrar; click Verify and we walk through them with a live DNS lookup until each one goes green.

DNS often takes a few minutes — sometimes longer. Hit Verify again every 60 seconds; once each record is green you can add mailboxes on that domain.

Once the domain verifies, open it and click Add address to register the exact mailbox you want to send from (e.g. [email protected]). The API only accepts from: values that match an active address on a verified domain — unknown local-parts are rejected even when the domain checks out, so you stay in control of which mailboxes can send.

Brand-new domains enter a warmup schedule automatically: the daily quota starts small and ramps up over a few weeks. Live state lives under Settings → Warmup — try not to bypass it unless you've already established sender reputation through another vendor.

3. Create an API key

Go to app.koltrix.com/api-keys (or Settings → API Keys in the dashboard). Click New key, give it a name like "Local dev", and tick the scopes you need:

• read — list resources, read messages and events
• send — send transactional email (REST + SMTP)
• newsletter — manage lists, subscribers, broadcasts, sequences
• contacts — manage CRM contacts
• * — full access (use sparingly)

The secret looks like kx_... — we show it exactly once. Copy it now and store it somewhere safe; we cannot recover it. If you lose it, revoke it and mint a new one.

export KOLTRIX_KEY="kx_..."

4. Send your first email

curl https://api.koltrix.com/api/v2/emails \
  -H "Authorization: Bearer $KOLTRIX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello from Koltrix",
    "body_html": "<h1>It works</h1><p>Sent via the API.</p>",
    "body_text": "It works\n\nSent via the API."
  }'

The response confirms the send was accepted and queued:

{
  "id": "01HX9C8...",
  "status": "queued",
  "queued": true,
  "tracking_url": "/api/v2/messages/01HX9C8...",
  "recipient_count": 1
}

A second later you should receive the message in your personal inbox. Poll GET /api/v2/messages/{id} (or open Inbox → Sent) to watch the status transition from queued to sent, and then to opened / clicked as the recipient interacts.

Always send an Idempotency-Key header on transactional sends. If your client retries after a network blip, we replay the cached response (with Idempotent-Replayed: true) for 24 hours instead of queuing the email twice.

If you don't see the message:

1. Check Settings → Email logs — every send shows up here with status, recipient, and the SMTP reply.
2. If status is bounced and the SMTP reply mentions DKIM/SPF, give DNS another minute to settle, then resend.
3. If status sticks at queued, check Settings → Warmup — you may have hit today's quota for a brand-new domain.

What next

• Read the full Authentication guide for scopes, key rotation, and SMTP auth.
• Send rich messages (attachments, threading, tracking opt-out) with Sending email.
• Set up a webhook so you hear about delivery, opens, clicks, and bounces without polling.
• Run your first newsletter with Newsletters, or automate a welcome series with Sequences.
• If you have a library that already speaks SMTP, point it at our SMTP relay — same pipeline, same tracking.