2fa Email Troubleshooting

Troubleshooting 2FA Authentication Code Emails

If users are reporting that they're not receiving their Two-Factor Authentication (2FA) code emails, this guide will help you diagnose and resolve the issue.

Quick Checklist

Before diving into detailed troubleshooting, verify these common issues:

• ✅ Check spam/junk folder
• ✅ Verify the email address is correct in the user record
• ✅ Check Email Logs in your Tadabase app
• ✅ Confirm SMTP settings are configured correctly
• ✅ Test with a different email provider (Gmail, Outlook, etc.)

Step 1: Verify Emails Are Being Sent

Check Email Logs

Tadabase logs all outgoing emails. To verify if the 2FA code was sent:

1. Go to your app in the Tadabase Builder
2. Navigate to Settings → Email Logs
3. Search for the user's email address
4. Look for entries with "Authentication Code" or "2FA" in the subject
5. Check the Status column:
   • Sent - Email was delivered to the mail server successfully
   • Failed - There was an error sending the email

If the email shows as "Sent", the issue is likely on the recipient's end (spam filters, email provider delays, etc.).

If the email shows as "Failed" or doesn't appear at all, check your SMTP configuration.

Step 2: Common Recipient-Side Issues

Spam/Junk Folder

The most common issue is emails being filtered to spam. Ask the user to:

1. Check their Spam/Junk folder
2. Search their entire mailbox for the sender address
3. Add your sending email address to their contacts/safe senders list

Corporate Email Filters

If the user is using a corporate email:

• Corporate email servers often have aggressive spam filters
• The IT department may need to whitelist your sending domain
• Some organizations block emails from unknown senders entirely

Email Provider Delays

Some email providers may delay delivery:

• Gmail: Usually instant, but can take 1-5 minutes during high volume
• Outlook/Hotmail: Can experience delays up to 10 minutes
• Yahoo: Known for occasional delivery delays
• Corporate Exchange: May queue messages for scanning

Recommendation: Wait 5-10 minutes before troubleshooting further.

Step 3: SMTP Configuration Issues

Verify SMTP Settings

If emails aren't being sent at all, check your SMTP configuration:

1. Go to Settings → Email Settings in your app
2. Verify your SMTP credentials are correct:
   • SMTP Host
   • Port (typically 587 for TLS, 465 for SSL)
   • Username
   • Password
   • Encryption method (TLS/SSL)
3. Send a test email to verify the configuration works

Common SMTP Provider Settings

SendGrid:

• Host: smtp.sendgrid.net
• Port: 587
• Username: apikey
• Password: Your API key

Gmail SMTP:

• Host: smtp.gmail.com
• Port: 587
• Username: Your Gmail address
• Password: App-specific password (not your regular password)

Step 4: Email Deliverability Issues

SPF/DKIM/DMARC Records

If you're using a custom domain for sending emails, ensure proper DNS records are configured:

• SPF (Sender Policy Framework): Tells email providers which servers can send on your behalf
• DKIM (DomainKeys Identified Mail): Adds a digital signature to verify email authenticity
• DMARC: Tells providers what to do with emails that fail SPF/DKIM checks

Contact your email service provider (SendGrid, etc.) for specific setup instructions.

Sender Reputation

Poor sender reputation can cause emails to be blocked or filtered:

• Avoid sending from free email domains (gmail.com, yahoo.com) for transactional emails
• Use a consistent "From" address
• Monitor bounce rates and remove invalid addresses

Step 5: User-Specific Troubleshooting

Verify User Email Address

1. Go to the Users table in your app
2. Find the affected user's record
3. Verify their email address is correct (no typos)
4. Check for extra spaces before/after the email

Test with Alternative Email

Ask the user to:

1. Temporarily update their account to use a different email address (e.g., personal Gmail)
2. Attempt login again
3. If the code arrives at the new address, the issue is with their original email provider

Step 6: Alternative Solutions

Resend the Code

Most 2FA implementations allow users to request a new code. Look for a "Resend Code" option on the 2FA input screen.

Admin Bypass (Temporary)

As an admin, you can temporarily disable 2FA for the affected user while troubleshooting:

1. Go to Settings → User Settings
2. Temporarily disable 2FA for the specific user or globally
3. Re-enable once the email issue is resolved

⚠️ Caution: Only use this as a temporary measure. Re-enable 2FA as soon as possible to maintain security.

Best Practices to Prevent 2FA Email Issues

1. Use a reliable SMTP provider like SendGrid, Mailgun, or Amazon SES
2. Set up proper DNS records (SPF, DKIM, DMARC)
3. Use a professional sending domain (not free email providers)
4. Monitor email deliverability through your SMTP provider's dashboard
5. Keep Email Logs enabled to troubleshoot issues quickly
6. Inform users to add your sending address to their contacts

Still Having Issues?

If you've tried all the above steps and users are still not receiving 2FA emails:

1. Gather the following information:
   • User's email address
   • Timestamp of login attempt
   • Screenshot of Email Logs
   • SMTP provider being used
2. Contact Tadabase support with this information

Related Articles

• User Settings - How to configure 2FA
• Email Settings - SMTP Configuration
• Using SendGrid for Emails
• User Security Feature Spotlight