API Reference

curl https://api.ghstmail.space/v1/aliases \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -d '{"label": "newsletter"}'

{
  "object": "alias",
  "id": "9c1f5e02-4a7b-4c3d-8e21-5b6a7c8d9e0f",
  "address": "newsletter.k7f2q@ghstmail.space",
  "label": "newsletter",
  "active": true,
  "expires_at": null,
  "emails_received": 0,
  "emails_forwarded": 0,
  "created_at": "2026-07-29T10:24:11.028Z",
  "updated_at": "2026-07-29T10:24:11.028Z"
}

Authorization: Bearer gm_live_kQ8xR2mN...

{
  "error": {
    "type": "validation_error",
    "code": "parameter_invalid",
    "message": "'domain': must match pattern",
    "param": "domain"
  },
  "request_id": "req_0850ce41f4fe1f98cf0990b9"
}

curl "https://api.ghstmail.space/v1/aliases?limit=20&starting_after=$LAST_ID" \
  -H "Authorization: Bearer $GHSTMAIL_KEY"

{
  "object": "list",
  "data": [ { "object": "alias", "...": "..." } ],
  "has_more": true
}

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1785320760

curl https://api.ghstmail.space/v1/aliases \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -H "Idempotency-Key: 7f3c1a90-signup-form" \
  -d '{"label": "signup"}'

# Self-destructs in 24 hours
curl https://api.ghstmail.space/v1/aliases \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -d '{"label": "free trial", "expires_in": 86400}'

# Or choose the address yourself
curl https://api.ghstmail.space/v1/aliases \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -d '{"local_part": "shopping"}'

curl -X PATCH https://api.ghstmail.space/v1/aliases/$ALIAS_ID \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -d '{"active": false}'

# Stop everything from one domain, across every alias
curl https://api.ghstmail.space/v1/filters \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -d '{"domain": "spam.example.com"}'

# Or scope it to a single alias
curl https://api.ghstmail.space/v1/filters \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -d '{"domain": "marketing.example.com", "alias_id": "'$ALIAS_ID'"}'

curl https://api.ghstmail.space/v1/messages \
  -H "Authorization: Bearer $GHSTMAIL_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "newsletter.k7f2q@ghstmail.space",
    "to": "someone@example.com",
    "subject": "Following up",
    "text": "Sent from an alias. Reply and it reaches me."
  }'

{
  "object": "message",
  "id": "<8b8c988c-2347-0a4a-a0c0-72fa77cb76f4@ghstmail.space>",
  "from": "newsletter.k7f2q@ghstmail.space",
  "to": ["someone@example.com"],
  "subject": "Following up",
  "status": "sent",
  "accepted": ["someone@example.com"],
  "rejected": [],
  "quota": {
    "per_hour": { "used": 1, "limit": 60 },
    "per_day": { "used": 1, "limit": 300 }
  },
  "sent_at": "2026-07-29T11:34:02.117Z"
}

# Body inline, from a file, from stdin, or in your editor
ghstmail send --from newsletter --to someone@example.com \
  --subject "Following up" --text "Sent from an alias."

ghstmail send --from newsletter --to someone@example.com \
  --subject "Report" --body ./report.txt

cat notes.md | ghstmail send --from newsletter --to a@example.com \
  --subject "Notes" --body -

# See exactly what would go on the wire, send nothing
ghstmail send --from newsletter --to a@example.com \
  --subject "hi" --text "hello" --dry-run

const API = "https://api.ghstmail.space/v1";

async function createAlias(label) {
  const res = await fetch(`${API}/aliases`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GHSTMAIL_KEY}`,
      "Content-Type": "application/json",
      // Safe to retry on a dropped connection: you get the
      // original alias back instead of a second one.
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ label }),
  });

  if (!res.ok) {
    const { error, request_id } = await res.json();
    throw new Error(`${error.code}: ${error.message} (${request_id})`);
  }
  return res.json();
}

const alias = await createAlias("hacker news");
console.log(alias.address);

import os, uuid, requests

API = "https://api.ghstmail.space/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['GHSTMAIL_KEY']}"

def create_alias(label: str) -> dict:
    res = session.post(
        f"{API}/aliases",
        json={"label": label},
        headers={"Idempotency-Key": str(uuid.uuid4())},
        timeout=30,
    )
    if not res.ok:
        body = res.json()
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return res.json()

def iter_aliases():
    """Walk every page without tripping the rate limit."""
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["starting_after"] = cursor
        page = session.get(f"{API}/aliases", params=params, timeout=30).json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["data"][-1]["id"]

print(create_alias("hacker news")["address"])

npm install -g ghstmail
ghstmail login

# The one you will actually use: create an alias and copy it
$ ghstmail new github
github.k7f2q@ghstmail.space
  copied to clipboard  ·  label: github  ·  never expires

# Throwaway that cleans itself up
$ ghstmail new "free trial" --expires 24h

# Did the signup email arrive?
$ ghstmail check github
github.k7f2q@ghstmail.space
  state      active
  received   1
  forwarded  1
  filters    none

# Block a sender across every alias
$ ghstmail filter add spam.example.com

# Pipe-friendly: stdout is only ever the data
$ ghstmail alias list --json | jq -r '.data[] | select(.active) | .address'

$ ghstmail watch github
Watching github.k7f2q@ghstmail.space every 5s. Ctrl-C to stop.

19:04:11  github.k7f2q@ghstmail.space  received +1  forwarded +1  delivered
19:06:40  github.k7f2q@ghstmail.space  received +1  forwarded +0  not forwarded, check filters