mailnix Docs
    mailnix / Quickstart

    Getting started

    Quickstart

    Sixty seconds from zero to a traced send. No signup, no credit card.

    Step 1 · Get a bearer token

    Every authenticated request to mailnix carries an OAuth 2.1 JWT. The shortest path to one is the seeded mailnix-anonymous-bootstrap client. One HTTP call returns a token and a freshly minted sandbox project.

    curl -X POST https://api.mailnix.ch/oauth/token \
  -d grant_type=client_credentials

# response
{
  "access_token": "mnx_live_a8f3…",
  "token_type":   "Bearer",
  "expires_in":   3600,
  "project":      "prj_7c2d"
}

    The token is audience-bound to https://api.mailnix.ch/v1 and scoped api:send + api:read. Use it as the Bearer credential on every REST call.

    Step 2 · Send your first message

    Anonymous projects always capture sends instead of relaying them to a real provider. That means you can fire as many requests as you like with no risk of accidentally emailing a real address.

    curl -X POST https://api.mailnix.ch/v1/messages \
  -H "Authorization: Bearer mnx_live_a8f3…" \
  -H "Content-Type: application/json" \
  -d '{
    "to":      ["jordan@example.com"],
    "from":    "noreply@example.com",
    "subject": "Hello from mailnix",
    "text":    "First send. Look at me go."
  }'

# response
{
  "trace_id": "a8f3c2d1-9b4e-4f7a-8c2d-1e5f6a3b9c8d",
  "outcome":  "captured.anonymous_project"
}

    The outcome tells you exactly what happened: relayed means the send hit a real provider; captured.anonymous_project means it landed in the sandbox.

    Step 3 · Read the trace

    Every send returns a public-shareable UUID. Open it to see the full pipeline record: routing decision, provider attempt, response code, and every delivery event afterwards.

    curl https://api.mailnix.ch/v1/traces/a8f3c2d1-9b4e-4f7a-8c2d-1e5f6a3b9c8d \
  -H "Authorization: Bearer mnx_live_a8f3…"

    Or open https://app.mailnix.ch/traces/<trace_id> in a browser. The same URL works for the public read-only view at https://api.mailnix.ch/share/traces/<trace_id>, redacted of PII.

    Step 4 · Claim the account when you're ready

    Anonymous projects are auto-deleted after 7 days of inactivity. To keep your work, claim the token by binding an email to it:

    curl -X POST https://api.mailnix.ch/v1/account/claim \
  -H "Authorization: Bearer mnx_live_a8f3…" \
  -d email=you@yourdomain.com

    We email a magic link; one click and the token converts to a real account. Same token, same project, same trace history; just now persistent.

    What's next