Skip to main content

Integration and account security

Wildmail API keys authenticate your application's requests to Wildmail. Endpoint signing secrets authenticate Wildmail webhook bodies to your receiver. They serve different purposes and rotate independently.

Credentials and permissions​

Create keys with the smallest required scope set, store their values in a secret manager, and send them as Authorization: Bearer <key>. A missing or invalid key returns 401. A valid key without the required scope returns 403. Account settings, key management, account deletion, and billing require a signed-in browser session instead of API keys. Consult the API reference.

API access is scoped to the individual account that owns the key. Account authorization also governs message content, raw email, attachments, and delivery records. Do not put credentials in URLs, client-side JavaScript, logs, or shared examples.

Webhook secrets are shown at creation or rotation. Deploy a new secret to your receiver when rotating. Each accepted message keeps its signing-key version for retries and replay. New messages use the newly rotated secret.

Treat message content as untrusted​

Validate webhook signatures against raw bytes before parsing. Inspect message.authentication in standard events for SPF, DKIM, DMARC, and ARC results, and distinguish permanent failures from temporary verification errors. Authentication results are signals for your policy. They do not make attachments safe.

Spam results in message.spam describe the email scan, not a malware verdict for each attachment. A false message.is_spam value does not prove the message is clean. Check the scan status and apply your own review policy. Validate types, limit downloads, and use suitable malware scanning or manual review for your workflow. Sender-supplied filenames and MIME types are untrusted. Never render HTML email directly into an unrestricted application page.

Raw message and attachment downloads use authenticated Wildmail message routes. They require an account API key with messages:read or a signed-in dashboard session. The URL alone does not authorize access. Access follows the current account retention policy and requires an active credential. Keep URLs and keys out of public logs and tickets.

Account protection​

Email code is the default email sign-in option. Password sign-in remains available. Codes contain six digits, expire after five minutes, allow three verification attempts, and work once. Resending replaces the previous code.

Settings supports TOTP authenticators, WebAuthn security keys, and single-use recovery codes. Both email-code and password sign-in require the enabled second factor. An email sign-in code is not a second factor. Google and GitHub sign-in use the provider’s security and do not use Wildmail’s second-factor challenge for email and password sign-ins. Linking a provider leaves protection on your email sign-ins intact.

Sign in with email to enroll or manage your authentication factors. Enrollment does not require password confirmation: confirm an initial authenticator code or complete browser security-key registration. Removing protection or replacing recovery codes requires your current password if you have one. Otherwise, request a fresh email code for that specific action. Save recovery codes when shown. Replacing them invalidates the previous set. You cannot remove your last security key unless a verified authenticator remains.

If you first use an email code for an existing account whose email was unverified, its previous password and linked providers are removed and its existing sessions are signed out. Your Wildmail account and enrolled authentication factors remain. Use password recovery to add a password again and relink providers afterward.

Password reset links expire after one hour and are single-use. Resetting a password revokes account sessions and preserves second-factor settings. Password changes using the current password sign out other sessions.

Webhook endpoints must use publicly reachable HTTPS on port 443. Private-network and loopback destinations are not supported. Configure the final HTTPS URL, because Wildmail does not follow redirects.