Authentication
Use a scoped API key for server integrations. Sign in to the hosted application to manage your account, API keys, security settings, and billing.
API keysโ
Create a key in Settings and grant only the scopes your integration needs. The plaintext key is shown once. Store it in a secret manager and keep it out of browser code, URLs, logs, and shared examples.
curl --fail-with-body "https://wildmail.app/api/messages" \
-H "Authorization: Bearer $WILDMAIL_API_KEY"
A key accesses resources in the account where it was created. A missing or invalid key returns 401. A valid key without the required scope returns 403. When an Authorization header is present, it takes precedence over browser session cookies, even if the key is invalid. Revoke a key in Settings to stop future requests using it.
Account settings, account deletion, key management, and billing require a signed-in browser session. API keys cannot perform those actions. See the API reference for each operation's required scope and authentication method.
Sign in to your accountโ
Email-code sign-in is the default option. Enter your email, request a six-digit code, and use it within five minutes. Each code works once and allows three verification attempts. Requesting a new code replaces the previous one. Password sign-in is also available. Registration is available only when enabled for the hosted service.
If you have enabled two-factor authentication, email-code and password sign-in also require your authenticator, security key, or recovery code. A sign-in email code is the first step and does not replace your second factor. Google and GitHub sign-in use the provider's authentication, so protect those accounts with the provider's security controls.
Use Settings to enroll and manage authenticators, security keys, and recovery codes. Sign in with email first to manage these settings. Save recovery codes when they are shown. Replacing them invalidates the previous set. Password reset links are single-use and expire after one hour. Completing a reset signs out existing sessions and preserves second-factor settings.
For more account-security behavior, see Integration and account security.
Webhook signaturesโ
A Wildmail API key authenticates requests from your application to Wildmail. An endpoint's signing secret lets your receiver authenticate incoming webhook requests. They are separate credentials and rotate independently.
Follow Verify and consume webhooks to validate signatures against the exact request bytes and deduplicate retries by event ID.