Skip to content

How we send ReminderIt's email

ReminderIt is our other product. Every reminder, receipt and support reply it sends goes through Koltrix. Here is the whole setup, including the awkward parts.

Venkat Swaroop5 min read
A black alarm clock standing on a wooden slatted table
Photo by Szűcs László on Unsplash
On this page(9 sections)
  1. One domain, three kinds of mail
  2. What does the setup look like at a glance?
  3. The sending side
  4. How do you avoid sending the same email twice?
  5. The part that actually changed how we work
  6. How do bounces and complaints get handled?
  7. What was awkward
  8. What would we copy if starting today?
  9. Numbers

Koltrix was not built as a product first. It was built because ReminderIt — our reminder-calling service — needed to send email, and the options were a transactional API that could not receive a reply and a mailbox host that could not send at volume. We ended up running both, badly, and then wrote the thing we wanted.

So the honest version of this case study is: ReminderIt is customer number one, we are the founder of both, and nothing below is a reference from a stranger. It is a description of a setup you can copy.

One domain, three kinds of mail

ReminderIt sends three things that people usually treat as three products:

  • Transactional mail — “your reminder was placed”, password resets, receipts. Machine-generated, must arrive, nobody expects a conversation.
  • Support mail — a human reading and answering questions at an address a human owns.
  • Replies to transactional mail — the category that usually disappears. Somebody hits reply on a receipt, and at a normal setup that mail hits a noreply@ black hole.

All three run on the same domain, with one set of DNS records, one DKIM key and one reputation to look after.

What does the setup look like at a glance?

Kind of mail Sent how Who reads replies What must hold
Transactional (reminder placed, reset, receipt) HTTP API call from the application The team inbox, via the signed Reply-To It arrives, once
Support replies A person answers from the shared inbox The same inbox, threaded The thread stays intact
Anything an older system sends over SMTP The SMTP relay, no code change The same inbox The same domain authenticates it

Everything shares the domain's SPF, DKIM and DMARC records. That is the main reason we run it this way: one authenticated identity to monitor instead of one per tool.

The sending side

The application posts to one endpoint. There is no SDK to install; it is a JSON POST with a bearer token.

curl https://api.koltrix.com/api/v2/emails \
  -H "Authorization: Bearer kx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Your reminder is set",
    "html": "<p>We will call you at 7:00.</p>"
  }'

Anything that already speaks SMTP points at the relay instead and needs no code change at all. The full reference, including idempotency keys and the delivery webhooks, is in the docs.

How do you avoid sending the same email twice?

A timeout does not tell the application whether the message was accepted, and the obvious reaction, retrying, is how customers end up with two copies of the same receipt. The Koltrix send API accepts an Idempotency-Key header, as the quickstart shows. Send the same key on every retry of the same logical message, and a retry of a send that already went through returns the original result instead of queuing a second email. Derive the key from the thing being sent, such as a reminder and its scheduled time, never from a random value generated per attempt, because a fresh key on each retry defeats the purpose. The post on idempotent send retries covers the response codes and how to retry from a client, and the general reasoning is in the idempotency keys guide.

The part that actually changed how we work

Every message sent through Koltrix carries a signed Reply-To that points back at the workspace. When someone replies to “your reminder was placed”, the reply arrives in the team inbox, threaded under the exact message that provoked it, with the customer's earlier mail attached to the same timeline.

That sounds small. In practice it removed an entire category of support work: we no longer have to ask “which email are you replying to?”, because the thread already says.

The token is signed rather than guessable for a reason worth stating: an unsigned reply+<id>@ address is an oracle, and anyone who can count could staple mail onto someone else's thread.

How do bounces and complaints get handled?

Automatically, or not at all. When a message hard-bounces or a recipient reports it as spam, the address is suppressed and later sends to it are skipped, with no one deciding case by case. A person who mistyped their address at signup should not get fifty more failed deliveries counted against the domain. The design questions are the same ones any application faces: what a suppression means for the account, how to show it to the user, and when to alert a human. A worked bounce and complaint pipeline walks through them, and hard versus soft bounces explains why only one of the two should suppress immediately.

What was awkward

  • DNS is still DNS. The wizard generates the records and checks them live, but a registrar that appends your domain to a TXT record you already fully qualified will still ruin your afternoon. We wrote a plain-English guide to the three records mostly so we could stop explaining it in support.
  • Reputation is earned slowly. A new domain sending to a cold list will be filtered no matter whose infrastructure it uses. We ramped ReminderIt's volume over weeks.
  • Bounce handling has to be automatic or it does not happen. Hard bounces and complaints suppress the address without anyone deciding to.

What would we copy if starting today?

If you want to reproduce this setup for your own product, this is the short list, in order:

  1. Pick one domain and authenticate it with SPF, DKIM and DMARC before sending anything.
  2. Send from an address a person owns, never noreply@; there is a full argument against it.
  3. Route replies to a shared inbox and make sure they thread under the message that caused them, which is what Customer Loop does.
  4. Put an idempotency key on every send and reuse it on retries.
  5. Suppress hard bounces and complaints automatically.
  6. Start at low volume and increase it over weeks.

None of this needs Koltrix specifically; the pattern works on any stack that can sign mail and receive replies. We built Koltrix so that the pieces would come together, not because the pieces are secret.

Numbers

We are not publishing volume, bounce-rate or time-saved figures on this site until they are measured from production and can be shown to anyone who asks. Made-up metrics are the reason most case studies are worthless, and we would rather have a short one that is true.

Start with Koltrix

Your domain, one inbox, and an API that sends.

A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.

SharePost on XLinkedIn