Real addresses on s7ortlynk.com. One call to wait for the mail.

Overview

A self-hosted, receive-only mail service. Mail for any address you create is accepted on port 25 and kept until you delete it. You reach it three ways: this API, the webmail at mail.s7ortlynk.com (also at s7ortlynk.com), and the Telegram bot.

Requests and responses are JSON unless noted. Every timestamp is ISO 8601 with an explicit +00:00 offset. An interactive console (Swagger UI) lives at /swagger and the machine-readable schema at /openapi.json.

Quick start

Three requests take you from nothing to a verification code. Paste your key below and every example on this page fills it in.

BASE="https://mail.s7ortlynk.com/api/v1"
KEY="YOUR_KEY"

# 1. a random, realistic address (send a local_part to choose one)
curl -s -X POST "$BASE/mailboxes" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{}'

# 2. use the address to sign up somewhere

# 3. block until the mail lands; codes are already extracted
curl -s "$BASE/messages/wait?mailbox=priya.nwosu31&timeout=60" \
  -H "X-API-Key: $KEY" | jq '{subject, code: .codes[0], links}'

import httpx

BASE = "https://mail.s7ortlynk.com/api/v1"
H = {"X-API-Key": "YOUR_KEY"}

with httpx.Client(base_url=BASE, headers=H, timeout=90) as api:
    box = api.post("/mailboxes", json={}).json()
    print(box["address"])            # priya.nwosu31@s7ortlynk.com

    # … trigger the sign-up email to box["address"] …

    msg = api.get("/messages/wait",
                  params={"mailbox": box["id"], "timeout": 60}).json()
    if msg:
        print(msg["codes"][:1], msg["links"][:1])

const BASE = "https://mail.s7ortlynk.com/api/v1";
const H = { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" };

const box = await (await fetch(`${BASE}/mailboxes`, {
  method: "POST", headers: H, body: "{}" })).json();

// … trigger the sign-up email to box.address …

const msg = await (await fetch(
  `${BASE}/messages/wait?mailbox=${box.id}&timeout=60`, { headers: H })).json();
console.log(msg?.codes[0], msg?.links[0]);

Authentication

Every endpoint except /health needs your API key in a header.

X-API-Key: YOUR_KEY

Get a key by messaging @AFK_MAIL_BOT on Telegram and sending /apikey. Sending /newkey issues a new one and the old key stops working at once.

A key sees only its own account. Asking for someone else's mailbox, message or attachment returns 404, exactly as if it did not exist, so ids cannot be probed.

Core ideas

Three ways to name a mailbox

Wherever a path or parameter takes a mailbox, you can pass its numeric id, its full address, or only the part before the @. These three point at the same mailbox:

/api/v1/mailboxes/7
/api/v1/mailboxes/priya.nwosu31@s7ortlynk.com
/api/v1/mailboxes/priya.nwosu31

Random addresses look like people

Creating a mailbox without a name gives it a realistic one built from common first and last names in six shapes: steven.gonzalez, priya.nwosu31, h.cook350, jisoo_wright, isabeldiaz13, jordanm6474. Some sign-up forms reject strings that look machine-made; these pass.

Message ids are a cursor

Ids only ever increase. Pass the last id you have seen as since_id to /messages or /messages/wait and you get only what is newer.

Codes and links come pre-extracted

Each full message carries codes and links. Codes are ranked by how close they sit to words like code, OTP or verify; years and order numbers are filtered out. Links that look like confirmation links sort first.

System

{ "ok": true, "domain": "s7ortlynk.com", "version": "1.2.0" }

{ "id": 1, "telegram_id": 935200729, "username": "admin",
  "is_admin": true, "mailbox_count": 3 }

Mailboxes

Only addresses that exist here receive mail. Anything else is turned away during the SMTP conversation with 550 No such mailbox here, before the sender transmits the message.

curl -s -X POST "$BASE/mailboxes" -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"local_part": "orders"}'

api.post("/mailboxes", json={"local_part": "orders"}).json()

await fetch(`${BASE}/mailboxes`, { method: "POST", headers: H,
  body: JSON.stringify({ local_part: "orders" }) });

{ "id": 7, "address": "orders@s7ortlynk.com", "local_part": "orders",
  "notify": true, "created_at": "2026-10-03T18:32:23.084585+00:00" }

Messages

{
  "id": 42,  "mailbox_id": 7,
  "msg_from": "GitHub <noreply@github.com>",
  "msg_to": "priya.nwosu31@s7ortlynk.com",
  "subject": "[GitHub] Please verify your device",
  "body_text": "Hi,\n\nYour verification code is 731902\n…",
  "body_html": "<html>…</html>",
  "size_bytes": 5120,  "received_at": "2026-10-03T18:41:07.512+00:00",
  "is_read": true,  "attachment_count": 0,  "attachments": [],
  "codes": ["731902"],
  "links": ["https://github.com/sessions/verified-device?token=…"],
  "auth_verdict": "pass",
  "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "verdict": "pass", "tls": "TLSv1.3" },
  "preview_url": "https://mail.s7ortlynk.com/p/2a.1.6aca8c94.YSpR4gEdWluxOwPrOobZqg"
}

Wait for mail

The request automation is built around. It holds the connection open until a new message arrives, then returns it in full.

curl -s "$BASE/messages/wait?mailbox=priya.nwosu31&timeout=60" \
  -H "X-API-Key: YOUR_KEY"

last = 0
while True:
    msg = api.get("/messages/wait", params={
        "mailbox": "priya.nwosu31", "since_id": last, "timeout": 60}).json()
    if msg:
        last = msg["id"]
        handle(msg)

let last = 0;
for (;;) {
  const r = await fetch(`${BASE}/messages/wait?mailbox=priya.nwosu31&since_id=${last}&timeout=60`, { headers: H });
  const msg = await r.json();
  if (msg) { last = msg.id; handle(msg); }
}

HTML & text views

Most mail arrives with both an HTML version and a plain-text version. This endpoint renders either one, safely.

{
  "id": 42,
  "html": "<p>Hi,</p><p>Your verification code is <b>731902</b></p>…",
  "format": "html",
  "available": ["html", "text"],
  "blocked_images": 1,
  "inlined_images": 0
}

Attachments

curl -OJ -H "X-API-Key: YOUR_KEY" "$BASE/attachments/9"

Web previews

Every message can be opened as a web page that looks like it does in a mail client: subject, sender, date, the verification code highlighted, and the mail's own design. No login is needed to open one.

curl -s "$BASE/messages?limit=1" -H "X-API-Key: YOUR_KEY" | jq -r '.[0].preview_url'

Sender checks

Anyone can type any name into the From line of an email. When a message arrives, the server checks whether the sending domain actually vouches for it, the same three checks Gmail and Outlook run.

The results are on every message as auth, with a one-word summary in auth_verdict:

Mail is never rejected or delayed because of these checks; they only label it. The same results are written into the stored source as an Authentication-Results header, and auth.tls records whether the message arrived over an encrypted connection.

Schemas

Mailbox

MessageSummary

MessageDetail

Everything in MessageSummary, plus:

Attachment

RenderedBody

Errors

Every error is {"detail": "…"}, written so you can show it to a person as it is.

SMTP replies

What another mail server hears when it delivers to mail.s7ortlynk.com on port 25. Useful when a sender reports a bounce.

Repeating the same RCPT TO in one transaction is accepted once; the message is stored a single time.

Limits

Reserved names

These can never be created, so abuse and bounce reports always reach the operator:

postmaster  abuse  admin  root  hostmaster  webmaster
noreply  no-reply  mailer-daemon  support

Rate limits

The API itself has none. Outbound mail is limited in practice by the receiving provider, which may slow down a burst from a new sending address.

Security

Domain & DNS

What it takes for Gmail, Outlook, iCloud and everyone else to deliver here, and to stop anyone faking mail from @s7ortlynk.com.

Webmail

A full inbox at mail.s7ortlynk.com. Sign in with your API key.

Telegram bot

Message @AFK_MAIL_BOT and send /start. New mail arrives as a notification with the code on top and buttons underneath.

When mail arrives

The notification shows who it is from, the subject, the code if there is one, and a short preview. It has two buttons:

Opening a message in the bot (/read or from /inbox) adds Attachments when there are any, and Delete.

Changelog