Getting Started

Quick start

1. Open the inbox and click Create temporary inbox.
2. Copy the address from the top bar.
3. Send mail to it from any app.
4. Watch it appear in real time.

DNS & MX setup

If you're hosting on your own domain, point an MX record at the server.

Behind Cloudflare? Set those records to DNS-only (grey cloud) — proxy mode breaks ACME and SSE. Set the IP's reverse DNS (PTR) to mail.you.com in your VPS panel.

Send a test message

# Install swaks
sudo apt install swaks

# Send a test (uses MX lookup)
swaks --to test@your-domain.com \
  --from probe@example.com

If the recipient exists, you'll see 250 Message Queued and the message appears in the inbox within a second.

REST API

The API surface mirrors mail.tm — existing clients (including @cemalgnlts/mailjs) work with just a baseUrl override.

# 1. List domains
curl https://api.you.com/domains

# 2. Create an inbox
curl -X POST https://api.you.com/accounts \
  -H 'Content-Type: application/json' \
  -d '{"address":"test@your-domain.com","password":"secret"}'

# 3. Get a token
curl -X POST https://api.you.com/token \
  -H 'Content-Type: application/json' \
  -d '{"address":"test@your-domain.com","password":"secret"}'

# 4. Read messages
curl https://api.you.com/messages \
  -H "Authorization: Bearer $TOKEN"

Real-time SSE

No polling. Subscribe to the Mercure hub with the same JWT you got from /token:

const es = new EventSource(
  `https://mercure.you.com/.well-known/mercure?topic=/accounts/${id}`,
  { headers: { Authorization: `Bearer ${token}` } }
);
es.onmessage = (e) => console.log("new mail:", JSON.parse(e.data));

Use the Mailjs client

Drop-in mail.tm client, point it at your server:

import Mailjs from "@cemalgnlts/mailjs";

const mailjs = new Mailjs({
  baseUrl: "https://api.you.com",
  baseMercure: "https://mercure.you.com/.well-known/mercure",
});

const acc = await mailjs.createOneAccount();
mailjs.on("arrive", (m) => console.log("new mail:", m.subject));