Quickstart

This walks from a fresh install to a delivered email.

1. Start the platform

cp .env.example .env
just up
just migrate

The stack comes up behind Traefik on subdomains of DOMAIN (localhost by default). Browsers resolve *.localhost to 127.0.0.1, so no hosts entries are needed.

URL	What it is
app.localhost	Dashboard
api.localhost	Public REST API
docs.localhost	This documentation
mailpit.localhost	Captured outgoing mail in development

2. Create an account and an API key

Register at app.localhost, create an organization, then open Settings → API keys and mint one. The key is shown once.

3. Verify a sender domain

Email is refused unless its sender address belongs to a verified domain.

curl -X POST http://api.localhost/v1/domains \
  -H "X-API-Key: $NOTIFYZR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

The response carries the DNS records to publish. Once they resolve, verify:

curl -X POST http://api.localhost/v1/domains/$DOMAIN_ID/verify \
  -H "X-API-Key: $NOTIFYZR_API_KEY"

In development, MailPit captures everything, so you can skip ahead using the sender the seed data provides.

4. Send

curl -X POST http://api.localhost/v1/send \
  -H "X-API-Key: $NOTIFYZR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": [{
      "type": "smtp",
      "sender": { "email_address": "hello@example.com", "alias": "Example" },
      "recipients": { "to": ["someone@example.com"] }
    }],
    "message": {
      "subject": "Hello from Notifyzr",
      "body": [{ "mime_type": "text/plain", "content": "It works." }]
    }
  }'

The response returns a message id immediately — delivery is asynchronous. The send is queued, a worker picks it up, signs it with DKIM if the domain is verified, and emits email.delivered or email.failed.

5. Watch it land

curl "http://api.localhost/v1/messages/$MESSAGE_ID" \
  -H "X-API-Key: $NOTIFYZR_API_KEY"

In development, open mailpit.localhost to read the message itself.

What to read next

• Contacts if you are building an audience.
• Templates to stop putting HTML in your application code.
• Automations to react to events without polling.