First Steps¶

Your server is running. Now let's actually use it. By the end of this page you will have created an organization, added a domain, set up a mailbox, sent a test email, and confirmed it arrived.

All management happens through the REST API on port 8083. Every endpoint under /api/v1/ requires an X-API-Key header -- which creates a chicken-and-egg problem on a fresh install: you need an API key to call the API, and there are none yet. The one-time bootstrap flow solves that.

Step 1: Bootstrap -- organization, domain, mailbox, API key¶

The recommended path is the interactive script:

./scripts/setup-first-user.sh

It asks for an organization name, an admin email address (the domain is derived from it), and a password -- then calls the API's one-time bootstrap endpoint and prints your first API key. The key is also saved to .api-key (gitignored) for convenience.

TOKEN=$(docker compose exec -T api cat /app/data/bootstrap-token | tr -d '\r\n')

curl -s -X POST http://localhost:8083/api/v1/bootstrap/ \
  -H "X-Bootstrap-Token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "My Company",
    "admin_email": "hello@example.com",
    "admin_password": "a-strong-password"
  }' | python3 -m json.tool

Export the key for the rest of this page:

export API_KEY=$(cat .api-key)

Step 2: Verify what bootstrap created¶

# Your domain, with the DNS records you need to publish
curl -s http://localhost:8083/api/v1/domains/ \
  -H "X-API-Key: $API_KEY" | python3 -m json.tool

# Your mailbox
curl -s http://localhost:8083/api/v1/mailboxes/email-accounts \
  -H "X-API-Key: $API_KEY" | python3 -m json.tool

Every API response uses the same envelope:

{
    "status": "success",
    "message": "Domains retrieved successfully",
    "data": { "...": "..." }
}

Step 3: Add another domain (optional)¶

Bootstrap created one domain. Additional domains are a plain API call:

curl -s -X POST http://localhost:8083/api/v1/domains/ \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.org"
  }' | python3 -m json.tool

DKIM signing keys are generated automatically and the response includes the DNS records to publish. An organization-scoped key always creates the domain in its own organization; a platform-scoped key must pass organization_id explicitly.

Step 4: Create another mailbox¶

A mailbox is an email account -- an address that can send and receive mail.

curl -s -X POST http://localhost:8083/api/v1/mailboxes/email-accounts \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "hello@example.com",
    "password": "a-strong-password"
  }' | python3 -m json.tool

The password is bcrypt-hashed and the mailbox is immediately usable over IMAP/POP3/SMTP. Storage quota defaults to 1 GB; pass storage_quota (in bytes) to change it. The domain part of the address must already exist as an active domain.

Step 5: Send a test email¶

The simplest end-to-end test is authenticated SMTP submission on port 587 -- the same path a real mail client uses:

python3 - <<'EOF'
import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "hello@example.com"
msg["To"] = "hello@example.com"
msg["Subject"] = "Test from Mailyte"
msg.set_content("If you can read this, your mail server works.")

with smtplib.SMTP("localhost", 587) as s:
    s.starttls()
    s.login("hello@example.com", "a-strong-password")
    s.send_message(msg)
print("sent")
EOF

Or use the built-in helper (injects directly via Postfix, no auth needed):

./start.sh            # option 20: Send test email

Step 6: Verify the email arrived¶

There are three ways to check.

Option A: Ask Dovecot directly¶

docker compose exec dovecot doveadm mailbox status -u hello@example.com messages INBOX

Option B: Connect with an email client¶

Point any IMAP client (Thunderbird, Apple Mail, Outlook) at your server:

Option C: Webmail¶

If you enabled a webmail profile (COMPOSE_PROFILES=roundcube in .env), log in at http://localhost:8880 with the mailbox address and password.

What you just did¶

flowchart LR
    A[Bootstrap] --> B[Publish DNS]
    B --> C[Create Mailboxes]
    C --> D[Send Email]
    D --> E[Verify Delivery]

1. Bootstrap -- one-time creation of the organization, first domain, first mailbox, and your API key.
2. DNS -- the domain record tells you exactly which MX/SPF/DKIM/DMARC records to publish.
3. Mailboxes -- real accounts with storage, usable by any IMAP/SMTP client immediately.
4. Send -- authenticated submission on 587 goes through the full Postfix/Rspamd path.
5. Verify -- Dovecot serves the delivered message over IMAP.

Quick reference: API endpoints used¶

The interactive reference at http://localhost:8083/api-docs covers every endpoint, and the API documentation section goes deeper.

Next step¶

Everything is working. Before you go further, read through Troubleshooting so you know where to look when things go sideways. (They will. It's email.)