Quickstart

Create a sandbox key

Go to app.genieos.pro → Settings → API keys, click New key, and choose Sandbox. Copy the key (gos_test_...); it will only be shown once.

Add your own address to the key's sandbox allowlist — sandbox keys can only send to allowlisted recipients.

Set the key in your shell

export GENIEOS_API_KEY="gos_test_..."

For long-lived setups, use a .env file or your secrets manager. Never commit a key — see Authentication for rotation.

Subscribe a webhook first

Pick any HTTPS URL you can hit — for local dev, ngrok, cloudflared, or a webhook.site URL all work.

curl https://api.genieos.pro/v1/webhooks \
  -H "Authorization: Bearer $GENIEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-tunnel.example/genieos",
    "events": ["send.queued", "send.delivered", "send.bounced"],
    "description": "Local dev"
  }'

The response includes a signing secret. Save it: you will need it to verify every payload. See Webhooks for the verifier.

Send your first email

Live path today is template-keyed send (aliases under /v1/transactional/* are not required for the loop):

curl https://api.genieos.pro/v1/templates/welcome/send \
  -H "Authorization: Bearer $GENIEOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "you@example.com",
    "variables": { "first_name": "Ada" },
    "metadata": { "order_id": "ord_demo_1" }
  }'

import { GenieOS } from '@genie-os/sdk';

// GENIEOS_API_KEY=gos_test_… (sandbox) or gos_live_… (production)
const gos = new GenieOS({ apiKey: process.env.GENIEOS_API_KEY! });

const res = await gos.templates.send('welcome', {
  to: 'you@example.com',
  variables: { first_name: 'Ada' },
  metadata: { order_id: 'ord_demo_1' },
});

console.log(res.id);

npm install @genie-os/sdk
node --env-file=.env --import tsx src/send.ts

from genieos import GenieOS

# GENIEOS_API_KEY=gos_test_… (sandbox) or gos_live_… (production)
gos = GenieOS()  # reads GENIEOS_API_KEY

res = gos.templates.send(
    "welcome",
    to="you@example.com",
    variables={"first_name": "Ada"},
    metadata={"order_id": "ord_demo_1"},
)

print(res.id)

pip install genieos
python send.py

Optional sandbox body field: "simulationScenario": "hard_bounce" (or soft_bounce / complained / failed). Default is delivered.

Confirm the loop

Within a few seconds your webhook should receive:

1. send.queued — GenieOS accepted the send
2. send.delivered (default) with data.simulation: { "sandbox": true, "scenario": "delivered" }

No mailbox accepted the message — the simulation marker is the proof.

Poll the same send:

curl "https://api.genieos.pro/v1/sends/<id>" \
  -H "Authorization: Bearer $GENIEOS_API_KEY"

List recent sends:

curl "https://api.genieos.pro/v1/sends?limit=25" \
  -H "Authorization: Bearer $GENIEOS_API_KEY"

Promote to production

When you are ready, swap the sandbox key for a gos_live_* key. The two keys share the same workspace, so templates and webhooks set up against sandbox work in production. Live keys contact your workspace connector (MailerSend / Relay / BYO ESP) and emit real send.delivered from the provider — still not on API accept (send.queued ≠ delivered).

Always send Idempotency-Key on production sends.