Auth & mailboxes.

The real, current shape of every /v1 route in this section, as shipped in warmhawk-core-engine. Every example is copy-pasteable against a real instance.

Base URL is https://your-instance/v1. Every route requires Authorization: Bearer <token> except POST /v1/auth/login (which issues the token) and the two OAuth routes (public, protected by a signed state param instead). This page covers auth and the full mailbox lifecycle — create, list, update, delete, and both connection paths (SMTP/IMAP credentials or Google/Microsoft OAuth).

POST /v1/auth/login

Authenticates against the engine’s own User table — separate from the Tier 1/2 dashboard’s own login. Rate-limited (10/min) and brute-force locked out per account, both layers active at once.

POST /v1/auth/login
Content-Type: application/json

{ "email": "you@yourcompany.com", "password": "YOUR_PASSWORD" }

{ "token": "YOUR_API_KEY" }

401 for invalid credentials (constant response shape whether the account exists or not, to avoid user enumeration). 429 with retryAfterMs once an account is locked from repeated failures.

Mailboxes

POST /v1/mailboxes — body

{
  "email": "you@yourcompany.com",       // required
  "domainId": "dom_a1b2c3",              // required — create the Domain first
  "provider": "SMTP_CUSTOM",             // optional, defaults to SMTP_CUSTOM
  "dailyCap": 25,                        // optional, defaults to 25
  "smtpHost": "smtp.yourdomain.com",
  "smtpPort": 587,
  "imapHost": "imap.yourdomain.com",
  "imapPort": 993,
  "authUsername": "you@yourcompany.com",
  "authPassword": "YOUR_SMTP_PASSWORD",  // encrypted at rest, never returned
  "senderName": "Sam Patel"              // optional — the From name; up to 80 characters
}

For Google Workspace / Microsoft 365, POST without authPassword, then complete the OAuth flow against the returned mailbox’s id — see Connecting mailboxes for the full walkthrough with both connection paths end to end.

POST /v1/mailboxes — sign-in check

When the body has an authPassword and an smtpHost or imapHost, the engine signs in to each of those servers once, side by side, before anything is saved. A wrong password is answered while you’re still holding it, not as a failed send hours later. Each check gives up after 10 seconds without an answer. The username is authUsername, or email when it’s left out. Hosts under the reserved test TLDs .test, .example and .invalid are never dialed.

{ "error": "This mailbox is already connected." }

{
  "error": "The mail server didn't accept that username and password. Google Workspace and Microsoft 365 usually need an app password here — or use Connect with Google or Connect with Microsoft instead."
}

The error is a sentence written for the person who typed the password, so it’s safe to show as is. The provider’s own reply (for example 535 5.7.8) goes to the engine’s log, not the response. Other 422 sentences you can get:

• IMAP password refused: “The IMAP server didn’t accept that username and password, so WarmHawk couldn’t read replies. Check the IMAP host — it usually takes the same password as SMTP.”
• Host doesn’t exist: “We couldn’t find a mail server called smtp.yourdomian.com. Check the SMTP host.”
• Nothing answers: “We couldn’t connect to mail.yourdomain.com on port 2525. Check the SMTP host and port — most mail servers use 587 or 465.” (For IMAP: “…most mail servers use 993.”)
• Anything else: “The SMTP server at mail.yourdomain.com didn’t accept the sign-in. Check the SMTP host, port, username and password.”