Issue #13: Implement Real Email Delivery (SMTP)

[spartan124]

Issue #6: Implement Real Email Delivery (SMTP)

Description

Due to verification blockers with the WhatsApp API, we are pivoting to prioritize Email OTP. Currently, our system uses a "Mock Email" service that only logs OTPs to the console.

This issue covers replacing the mock service with a real SMTP integration (using fastapi-mail) so users actually receive the OTP code in their inbox.

Key Changes & Requirements

1. Dependencies

• Install fastapi-mail.
• This library handles non-blocking (async) email sending and template management seamlessly.

2. Configuration (app/core/config.py)

Add the following environment variables to Settings (and your .env file):

• MAIL_USERNAME: (e.g., your generic gmail address)
• MAIL_PASSWORD: (The "App Password" generated from Google Security settings, NOT your login password)
• MAIL_FROM: (e.g., no-reply@svaay.com or same as username)
• MAIL_PORT: 587
• MAIL_SERVER: smtp.gmail.com
• MAIL_STARTTLS: True
• MAIL_SSL_TLS: False

3. Service Implementation (app/services/email.py)

• Refactor: Replace the send_mock_email function with a class-based service using FastMail.
• Template: Create a simple HTML template for the email body to look professional.

  Subject: Your Login Code
  Body: "Your verification code is: 123456. It expires in 5 minutes."

4. Worker Integration (app/worker.py)

• Update the consumer loop to initialize the FastMail instance.
• Ensure the send_message call is awaited properly to prevent blocking the worker.

Implementation Plan

• Install: uv add fastapi-mail
• Config: Update .env with SMTP credentials (recommend using Gmail with an App Password for dev).
• Service: Create app/services/email.py with the send_otp_email(email, code) function.
• Worker: Wire up the worker to call the real email service.
• Cleanup: Remove the "Mock" logging statements.

Testing Checklist

• Credentials: Verify SMTP connection works (no "Authentication Failed" errors).
• Delivery: Trigger /send-otp -> Check actual Gmail/Outlook inbox.
• Spam Check: Ensure the email doesn't immediately go to Spam (basic subject line check).
• Async: Confirm the API returns immediately while the email sends in the background.

💡 Tech Tip: Getting Gmail Credentials

If you are using a standard Gmail account for testing:

1. Go to Google Account -> Security.
2. Enable 2-Step Verification.
3. Search for "App Passwords".
4. Create one named "OTP Service".
5. Use that 16-character string as your MAIL_PASSWORD.