Domain Setup

Domain verification is a one-time step required before your school can use Tier 2 (Stalwart on your own domain) or Tier 3 (Google Workspace) email provisioning. It also unlocks your live API key.

---

Why verification is required

When you provision student emails on your school's domain (e.g. @loretto.edu.ng), Nexa needs to confirm that:

1. You control that domain — so no tenant can impersonate another school's address
2. The correct DNS records are in place — so email is actually delivered

Passing verification unlocks your nxa_live_... key and allows nexa.email.create() to provision real accounts.

---

Tier 2 — Custom Domain (Stalwart)

Nexa manages the mail server infrastructure; your school provides the DNS records.

Step 1 — Enter your domain in the dashboard

Go to Dashboard → Domain and enter your school's domain (e.g. loretto.edu.ng). Nexa registers the domain with Stalwart and returns the DNS records you need to add.

Step 2 — Add DNS records at your registrar

You will receive records similar to these. Add them exactly as shown at your domain registrar (GoDaddy, Namecheap, Cloudflare, etc.):

DNS changes typically propagate within 5–30 minutes, though it can take up to 48 hours.

Step 3 — Click "Verify domain"

Once the records are live, click Verify domain in the dashboard. Nexa performs live DNS lookups and confirms all required records resolve correctly.

On success:

• emailDomainVerified is set to true on your tenant record
• Your live API key (nxa_live_...) is unlocked
• You can now use nexa.email.create() with tier: "tier-2-stalwart"

Re-verification

If you change DNS providers or DNS records are accidentally removed, click Re-verify at any time from the Dashboard → Domain page.

---

Tier 3 — Google Workspace

Your school's Google Workspace account manages the mailboxes. Nexa uses a service account to provision students programmatically.

Step 1 — Create a Google service account

In the Google Cloud Console:

1. Create a project (or use an existing one)
2. Enable the Admin SDK API
3. Create a Service Account
4. Create a key (JSON format) and download it
5. In your Google Workspace Admin Console, delegate domain-wide authority to the service account with the scope: https://www.googleapis.com/auth/admin.directory.user

Step 2 — Save credentials in the dashboard

Go to Dashboard → Email Settings and paste your service account JSON. Nexa:

1. Encrypts the JSON (AES-256-GCM) and stores it in your tenant record
2. Makes a test API call to Google Admin to confirm the credentials work
3. On success — stores the credentials, sets activeTier to tier-3-google, and unlocks your live key

Step 3 — (Optional) Verify your domain

If you also want to use Stalwart (Tier 2) as a fallback, go through the Tier 2 DNS verification steps as well. If you only use Google Workspace, domain DNS verification is not required — Google already controls your domain's email routing.

---

Switching tiers

You can change email tiers at any time from Dashboard → Email Settings:

Existing provisioned accounts are not migrated when you switch tiers. New accounts created after the switch use the new tier.

---

API key states

---

Troubleshooting

"Verification failed — MX record not found" DNS propagation may not be complete. Wait 15 minutes and try again. Use dig MX yourdomain.com to check current DNS resolution.

"Verification failed — SPF record incorrect" Ensure the TXT record is on the root domain (yourdomain.com), not a subdomain. Some registrars show this as @.

"Google credentials invalid" Check that domain-wide delegation is enabled for the service account in Google Workspace Admin. The scope must include https://www.googleapis.com/auth/admin.directory.user.

Live key still shows locked after verification Refresh the dashboard. If it still shows locked, the verification may not have completed — click Re-verify from the Domain page.

---

What's next

• Student Emails — start provisioning accounts once your domain is verified
• Webhooks — receive email.created and email.bulk_completed events