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.

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.

Send your first email

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

import { GenieOS } from 'genieos';

const mg = new GenieOS();

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

console.log(res.id);

npm install genieos
# pnpm add genieos
# yarn add genieos
# bun add genieos
# deno add npm:genieos
node --env-file=.env --import tsx src/send.ts

from genieos import GenieOS

mg = GenieOS()

res = mg.templates.send(
    to="you@example.com",
    template="welcome",
    variables={"first_name": "Ada"},
)

print(res.id)

pip install genieos
# uv add genieos
# poetry add genieos
# pdm add genieos
python send.py

Inspect the result

Open app.genieos.pro → Events. You\u2019ll see a fresh transactional.queued row with the same id the API returned. Because you used a sandbox key, no transactional.delivered will follow — sandbox stops at queued.

You can also tail this from the terminal:

genie events tail

(See the CLI docs for installing genie.)

Subscribe a webhook

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": ["transactional.delivered", "transactional.bounced"],
    "description": "Local dev"
  }'

The response includes a signing_secret that begins whsec_.... Save it: you\u2019ll need it to verify the signature on every payload. See Webhooks for a 5-line verifier in any language.

Promote to production

When you\u2019re ready, swap the sandbox key for a gos_live_* key and point your app at production. The two keys share the same workspace, so templates, sequences, and webhooks you set up against sandbox automatically work in production.