Runtime
Live server configuration from environment.
| Base URL | https://api.airhux.net |
| API prefix | /v1 |
| Port | 4000 |
| Environment | production |
| Redis / queues | Enabled (BullMQ) |
| Health | GET /health |
| Quick start | POST /v1/auth/register → POST /v1/domains → POST /v1/api-keys → POST /v1/emails/send |
Authentication matrix
How each API surface is protected.
| Method | Used by |
|---|---|
| Public | Register, login, plans, tracking pixels, inbound MTA hooks, bounce/complaint ingestion |
| JWT | Dashboard CRUD — domains, API keys, mailboxes, webhooks, billing, collaboration |
| JWT + Admin | Platform admin — customers, plans, abuse, IP pools, billing overview |
| API Key | Transactional send API — POST /v1/emails/send, bulk, status |
| Webmail JWT | AI assistant endpoints after mailbox webmail login |
Webhook events
HMAC-SHA256 signed POSTs with up to 6 retry attempts.
Prisma data model
MySQL database airhuxeps — multi-tenant account hierarchy.
Authentication & Accounts
User registration, JWT sessions, rich account settings, and subaccounts.
- Register creates Account (sandbox) + User with customer role
- JWT payload: userId, email, accountId
- Account settings: IP allowlist, sending defaults, theme, integrations
- Subaccounts inherit parent; dedicated IPs from domain→pool routing
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/auth/register |
Public | Create account + user |
| POST | /v1/auth/login |
Public | Email/password login |
| GET | /v1/auth/me |
JWT | Current user profile |
| GET | /v1/account |
JWT | Account profile + entitlements |
| PATCH | /v1/account/settings |
JWT | Update account settings |
| POST | /v1/account/subaccounts |
JWT | Create subaccount |
Transactional Email API
REST send API with API keys, templates, idempotency, bulk send, and status lookup.
- Single and bulk send with tags and template variables
- Idempotency keys prevent duplicate sends
- Sandbox mode queues but never delivers
- Open/click tracking injected per domain settings
Business flow
Bearer token → SHA-256 lookup, scopes, IP allowlist, sandbox flag
html|text required, recipient format, idempotency replay
Verified domain or sender identity (bypass in sandbox)
Subscription quota (402), per-minute rate limit (429)
Optional templateId + variable substitution
Content score ≥ 80 → block + AbuseReport (403)
Filter blocked recipients; skip suppressed addresses
Rewrite links + 1×1 open pixel when domain.trackingEnabled
Email + recipients saved; webhook email.queued; usage recorded
BullMQ email-send queue or inline SmtpDeliveryService
DKIM sign → MX resolve → IP pool route → smart host relay
email.sent / email.delivered / email.failed webhooks + tracking
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/emails/send |
API Key | Send one email |
| POST | /v1/emails/bulk |
API Key | Send up to N messages |
| GET | /v1/emails/:id |
API Key | Email status + recipients |
Domains & Deliverability
SPF/DKIM/DMARC verification, DKIM signing, Domain Connect, sender identities, IP pools.
- Auto-generate DKIM keys on domain create
- DNS verification for SPF + DKIM records
- Domain Connect one-click DNS apply URL
- Sender identity token verification for From addresses
- IP pools with warmup and domain routing
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/domains |
JWT | Add sending domain |
| POST | /v1/domains/:id/verify |
JWT | Check DNS records |
| GET | /v1/domains/:id/domain-connect |
JWT | Domain Connect URL |
| POST | /v1/sender-identities |
JWT | Add sender address |
| GET | /v1/ip-pools |
JWT + Admin | List IP pools |
Hosted Business Email
Full mailbox hosting — aliases, groups, forwarding, IMAP/POP3/SMTP, webmail, spam filter.
- Mailboxes on verified domains with 5GB default quota
- Aliases, distribution groups, forwarding with cycle detection
- IMAP/POP3/SMTP auth endpoints for mail clients
- Webmail login issues JWT for AI assistant
- Spam filter levels: off/low/medium/high
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/business-email/mailboxes |
JWT | Create mailbox |
| POST | /v1/business-email/aliases |
JWT | Create alias |
| POST | /v1/business-email/groups |
JWT | Create group |
| POST | /v1/business-email/forwarding |
JWT | Set forwarding |
| POST | /v1/business-email/imap/auth |
Public | IMAP login |
| POST | /v1/business-email/webmail/login |
Public | Webmail JWT |
Inbound Mail Processing
MIME ingestion, rules engine, spam/virus scanning, quarantine, and optional forwarding.
- MTA webhook receives raw MIME
- Inbound rules: regex match → deliver/forward/reject/quarantine
- Premium spam heuristics gated by plan
- ClamAV or heuristic virus scan
- Collaboration: assign, comment, shared contacts
Business flow
POST /v1/inbound-mail/receive — raw MIME payload
Extract headers, body, attachments from raw message
Match mailbox or alias on verified domain
Regex on from/to/subject → deliver|forward|reject|quarantine
Mailbox level + premium tier; block or quarantine (score ≥ 50)
ClamAV or heuristic when plan entitles antivirus
Mailbox storage limit before accept
InboundMessage persisted; webhook inbound.received
Optional outbound resend as Fwd: via EmailsService
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/inbound-mail/receive |
Public | MTA MIME ingest |
| GET | /v1/inbound-mail/messages |
JWT | List inbox messages |
| POST | /v1/inbound-mail/rules |
JWT | Create inbound rule |
| GET | /v1/collaboration/messages |
JWT | Shared inbox |
AI Email Assistant
Claude-powered tools for webmail users — summarize, reply, grammar, translate, classify.
- Requires plan feature aiAssistant
- Webmail JWT auth (type: webmail)
- Anthropic API or local fallback
- Token usage metered in AiInteraction
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/business-email/ai-assistant/summarize |
Webmail JWT | Summarize message |
| POST | /v1/business-email/ai-assistant/reply |
Webmail JWT | Draft reply |
| POST | /v1/business-email/ai-assistant/grammar |
Webmail JWT | Fix grammar |
| POST | /v1/business-email/ai-assistant/translate |
Webmail JWT | Translate text |
Reputation & Compliance
Suppressions, bounces, complaints, content abuse scanning, and admin abuse reports.
- Per-account suppression list (bounce, complaint, unsubscribe, manual)
- Hard bounces auto-suppress via DSN processing
- FBL complaints auto-suppress + webhook
- Outbound content scan blocks score ≥ 80
- Admin can list and resolve abuse reports
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/suppressions |
JWT | List suppressions |
| POST | /v1/suppressions |
JWT | Add suppression |
| POST | /v1/bounces/process |
Public | Process DSN |
| POST | /v1/bounces/complaint |
Public | Process FBL |
| GET | /v1/admin/abuse |
JWT + Admin | List abuse reports |
Billing, Usage & Webhooks
Plans, subscriptions, monthly usage metering, and signed webhook event delivery.
- Public plan catalog with feature gates (AI, antivirus, collaboration)
- Monthly UsageRecord: emailsSent, emailsDelivered
- Inactive subscription blocks sending
- Webhooks: HMAC-SHA256 signature, 6 retry attempts
- Redis queue or inline webhook dispatch
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/plans |
Public | List plans |
| GET | /v1/subscriptions/me |
JWT | Current subscription |
| GET | /v1/usage |
JWT | Monthly usage stats |
| POST | /v1/webhooks |
JWT | Subscribe to events |
| GET | /v1/track/open/:emailId |
Public | Open tracking pixel |
| GET | /v1/track/click/:emailId |
Public | Click redirect |
Platform Admin
Customer management, email inspection, plan CRUD, billing dashboard, IP pool admin.
- CRUD customers, users, subscription assign/cancel
- List all emails across accounts
- MRR/ARR billing overview
- Plan management and feature configuration
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /v1/admin/customers |
JWT + Admin | List customers |
| GET | /v1/admin/emails |
JWT + Admin | List emails |
| GET | /v1/admin/billing/overview |
JWT + Admin | Billing dashboard |
| POST | /v1/admin/plans |
JWT + Admin | Create plan |