Two-Factor Authentication

MailTrixy supports two-factor authentication (2FA) to add an extra layer of security beyond passwords. Users can choose between TOTP-based authenticator apps or SMS verification.

TOTP Setup (Authenticator App)

Time-based One-Time Password (TOTP) is the recommended 2FA method. It works with any standard authenticator app such as Google Authenticator, Authy, or 1Password.

Setup Steps

  1. Navigate to Settings → Security → Two-Factor Authentication.
  2. Click Enable Two-Factor Authentication.
  3. Scan the QR code displayed on screen with your authenticator app.
  4. Enter the 6-digit verification code from your authenticator app to confirm setup.
  5. Save the recovery codes displayed after successful verification.

Once enabled, you will be prompted for a 6-digit TOTP code after entering your password on every login. The code refreshes every 30 seconds. 

// TOTP configuration
'two_factor' => [
    'algorithm' => 'sha1',
    'digits' => 6,
    'period' => 30,       // seconds
    'window' => 1,        // accept codes 1 period before/after
    'issuer' => 'MailTrixy',
],

Recovery Codes

When 2FA is enabled, MailTrixy generates 8 single-use recovery codes. These codes can be used to access your account if you lose access to your authenticator app or phone.

  • Each recovery code can only be used once.
  • Recovery codes are stored encrypted in the database using AES-256-CBC.
  • You can regenerate a new set of recovery codes from the security settings page at any time. Regenerating codes invalidates all previous codes.
  • Store recovery codes in a secure location such as a password manager.
Example recovery codes (save these securely):

ABCD-1234-EFGH
IJKL-5678-MNOP
QRST-9012-UVWX
YZAB-3456-CDEF
GHIJ-7890-KLMN
OPQR-1234-STUV
WXYZ-5678-ABCD
EFGH-9012-IJKL

SMS Two-Factor Authentication

For users who prefer not to use an authenticator app, MailTrixy offers SMS-based 2FA as an alternative. A 6-digit code is sent to the user's verified phone number during login.

Setup Steps

  1. Navigate to Settings → Security → Two-Factor Authentication.
  2. Select SMS Verification as your 2FA method.
  3. Enter your phone number with country code (e.g., +1-555-0123).
  4. Verify your phone number by entering the code sent via SMS.
  5. Save your recovery codes.

SMS 2FA requires a configured SMS provider in the admin panel. MailTrixy supports Twilio, Vonage (Nexmo), and AWS SNS for SMS delivery. The admin must configure at least one SMS provider before users can enable SMS-based 2FA. 

// .env SMS configuration (example with Twilio)
TWILIO_SID=your-twilio-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_PHONE_NUMBER=+15551234567

Enforcing 2FA for Admins

Workspace owners and super admins can enforce 2FA for all users with specific roles. When enforced, users without 2FA enabled will be redirected to the 2FA setup page on their next login and will not be able to access the application until setup is complete.

  • Enforce for admins only — All users with the admin role must have 2FA enabled.
  • Enforce for all members — Every workspace member must have 2FA enabled.
  • Optional — 2FA is available but not required (default setting).
  • Grace period — When enforcement is turned on, existing users get a 7-day grace period to enable 2FA before they are locked out.

Configure 2FA enforcement from Admin Panel → Settings → Security or at the workspace level from Workspace Settings → Security.

2FA for API Access

API tokens bypass 2FA verification since they are pre-authenticated. However, 2FA is required when creating new API tokens through the web interface. This ensures that only users who have passed 2FA can generate new access tokens.

  • Token creation via the dashboard requires a fresh 2FA confirmation (code entered within the last 5 minutes).
  • Token creation via the API requires the current token to have been created by a 2FA-verified session.
  • Revoking all tokens can be done from the security settings page and requires 2FA confirmation.
  • When a user disables 2FA, all their existing API tokens are automatically revoked for security.

Troubleshooting 2FA

Common issues and solutions for two-factor authentication:

Issue Solution
TOTP code rejected Ensure your device's clock is synchronized. TOTP codes are time-sensitive and require accurate system time.
Lost authenticator app Use one of your recovery codes to log in, then disable and re-enable 2FA with a new device.
Lost recovery codes Contact your workspace admin to temporarily disable 2FA on your account.
SMS not received Check that the phone number includes the correct country code. Verify the SMS provider configuration in admin settings.
Too many failed attempts Wait 10 minutes for the rate limit to reset, or use a recovery code to bypass.
Last updated 10/03/2026