Documentation

Everything you need to know about NOVA Mail — encrypted, private, and ad-free, with no AI on your mailbox by default.

API Reference

Every endpoint below is implemented by NOVA's Pages Functions and reachable at https://nova-email.com. Authenticated mailbox routes take Authorization: Bearer <token>.

Authentication

Base https://nova-email.com/api/auth

Method	Route	Description
POST	/register	Create an account: email, password, captcha_token, account_type (standard/kid), parent_email for kid accounts.
POST	/login	Password login: email, password, captcha_token. Returns token + user_id + email, or { mfa_required } / { otp_required } when a second factor is on.
POST	/otp-verify	Verify an email one-time code: otp_id + code, or { action: "resend", delivery_email } to send a new code.
POST	/send-code	Send the registration verification code to a personal email.
POST	/mfa/verify	Verify a TOTP code: mfa_session_id + code.
POST	/passkey/options	Get WebAuthn assertion options for an email before passkey sign-in.
POST	/passkey/verify	Submit a completed WebAuthn assertion and finish the login.
POST	/logout	Revoke the current session token.
GET	/check	Validate the session token in the Authorization header.

Mailbox

Base https://nova-email.com/api/mailbox — requires Authorization: Bearer <token>. Message flags: 1 = read, 2 = starred.

Method	Route	Description
GET	/messages	List messages. Query: folder (inbox\|sent\|drafts\|archive\|trash\|spam\|starred\|…), folder_id (custom folder), q (search). Returns { messages, next_cursor }.
GET	/messages/:id	One message with parsed recipients_to / recipients_cc arrays and attachment metadata.
POST	/messages	Send an email: from_field, to, cc, bcc, subject, body (+ optional attachment).
POST	/messages/:id/read	Mark a message as read (flag 1).
POST	/messages/:id/unread	Mark a message as unread (clear flag 1).
POST	/messages/:id/star	Toggle the starred flag (bit 2).
POST	/messages/:id/pin	Toggle the pinned flag (bit 8).
POST	/messages/:id/snooze	Snooze a message until a timestamp.
POST	/messages/:id/unsnooze	Remove a snooze.
POST	/messages/:id/move	Move a message to a folder: { target_folder_id }.
POST	/messages/:id/spam	Report a message as spam and move it to the spam folder.
POST	/messages/:id/not-spam	Mark a message as not spam and restore it to the inbox.
POST	/messages/:id/block-sender	Block the sender and discard their future messages.
DELETE	/messages/:id	Delete (trash) a message.
GET	/messages/:id/attachments/:name	Download an attachment.
POST	/send/undo	Undo a send within the recall window.
POST	/drafts	Save a draft: subject, body, is_html. Creates a new draft.
GET	/folders	List folders with id, name, type, unread_count.
POST	/folders	Create a custom folder: { name }.
PUT	/folders/:id	Rename a custom folder.
DELETE	/folders/:id	Delete a custom folder.
GET	/labels	List labels.
POST	/labels	Create a label: { name }.
PUT	/labels/:id	Rename a label.
DELETE	/labels/:id	Delete a label.
GET	/messages/:id/labels	Labels applied to a message.
POST	/messages/:id/labels	Apply labels: { label_ids }.
DELETE	/messages/:id/labels/:labelId	Remove a label from a message.
GET	/contacts	List contacts (search: q).
POST	/contacts	Create a contact: { email, name }.
PUT	/contacts/:id	Update a contact.
DELETE	/contacts/:id	Delete a contact.
GET	/settings	Get account settings.
PUT	/settings	Update account settings.
GET	/aliases	List email aliases.
POST	/aliases	Create an alias.
POST	/aliases/:id/toggle	Enable or disable an alias.
DELETE	/aliases/:id	Delete an alias.
GET	/filters	List mail filters.
POST	/filters	Create a filter.
PUT	/filters/:id	Update a filter.
DELETE	/filters/:id	Delete a filter.
GET	/vacation	Get auto-reply settings.
PUT	/vacation	Set auto-reply settings.
GET	/forwarding	Get forwarding settings.
PUT	/forwarding	Update forwarding settings.
GET	/domains	List verified custom domains.
POST	/domains	Add a custom domain.
POST	/domains/verify	Verify a custom domain by DNS record.
DELETE	/domains/:name	Remove a custom domain.
GET	/external-accounts	List connected IMAP accounts.
POST	/external-accounts	Connect an IMAP account.
DELETE	/external-accounts/:id	Disconnect an IMAP account.
POST	/sync-account	Trigger an IMAP resync.
GET	/sessions	List active sessions.
POST	/sessions/revoke-all	Revoke all sessions.
DELETE	/sessions/:id	Revoke one session.
GET	/two-factor	Check whether TOTP is enabled.
POST	/two-factor/setup	Start TOTP setup: returns an otpauth URI.
POST	/two-factor/enable	Confirm and enable TOTP with a code.
POST	/two-factor/disable	Disable TOTP.
POST	/two-factor/recovery-codes	Generate recovery codes.
GET	/passkeys	List passkeys on the account.
POST	/passkeys/register-options	Get WebAuthn creation options.
POST	/passkeys/register	Register a passkey.
DELETE	/passkeys/:id	Remove a passkey.
GET	/security/blocklist	List blocked senders.
GET	/security/allowlist	List allowed senders.
POST	/security/lists	Block or allow a sender: { email, list }.
DELETE	/security/lists	Remove a sender from a list.
GET	/parental-controls	Get kid-account supervision settings.
PUT	/parental-controls	Update supervision settings.
GET	/subscriptions	List mailing-list subscriptions.
POST	/subscriptions	Add a subscription monitor.
PUT	/subscriptions/:id	Update a subscription.
DELETE	/subscriptions/:id	Remove a subscription.
POST	/subscriptions/:id/unsubscribe	Trigger an unsubscribe request.
GET	/keys	Get the identity key bundle.
POST	/keys	Provision encryption keys.
GET	/export	Export your mailbox data.
GET	/audit-log	Read account audit events.
GET	/user	Account profile: email, display_name, plan.
POST	/password-change	Change the account password.
GET	/version	API version string.

Additional endpoints

Standalone routes on the same API surface.

Method	Route	Description
POST	/api/account/delete	Request account deletion (sends a confirmation).
POST	/api/disposable/create	Instant one-click disposable email address.
POST	/api/disposable/delete	Delete a disposable address.
POST	/api/report	Report an abusive message.
POST	/api/feedback	Submit product feedback.
GET	/api/cli/version	Latest CLI version for upgrades.
GET	/status	Service status / health probe.
GET	/api/ai	AI assistant status (opt-in).
POST	/api/ai/enable	Enable the AI assistant.
POST	/api/ai/send	Have the assistant send a drafted reply.
GET	/api/ai/mailbox	List AI-assistant message snapshots.
POST	/api/inbound/*	Inbound webhook receiver (Postmark + custom SMTP deliveries).

Error Reference

ERR_AUTH_001

Invalid email or password

Double-check your credentials. Passwords are case-sensitive and hashed with Argon2id.

ERR_AUTH_002

Session expired

Sign out and sign back in. Sessions last 24 hours.

ERR_AUTH_003

Invalid verification code

Enter the 6-digit code sent to your email. Codes expire after 10 minutes.

ERR_AUTH_004

Email verification required

Verification is mandatory. Complete email verification during registration.

ERR_REG_001

Email already taken

Choose a different email address. Check availability on the registration page.

ERR_REG_002

Maximum 5 accounts per email

Each verified email can register up to 5 NOVA accounts.

ERR_REG_003

Parent account not found

The parent must create their NOVA account before the kid account.

ERR_REG_004

Must agree to Terms of Service

Check the agreement box on the registration or disposable creation page.

ERR_SEND_001

Failed to send to recipient

The recipient's mail server rejected the message. Check the address and try again.

ERR_SEND_002

Sender unauthenticated

SPF/DKIM records need to be configured for nova-email.com.

ERR_SEND_003

Recipient not found

The recipient address does not exist on NOVA. Check for typos.

ERR_SYNC_001

IMAP connection failed

Check your IMAP server address and port. Ensure app passwords are used.

ERR_SYNC_002

Invalid IMAP credentials

Use an app-specific password, not your regular email password.

Documentation

Getting Started

Security & Encryption

Email Verification

Parental Controls

Connected Accounts

Error Reference

API Reference

Authentication

Mailbox

Additional endpoints

Error Reference