Email Verification for Fintech Onboarding

import hashlib
import os
from datetime import datetime
from mailbeam import Client
from fastapi import HTTPException

mb = Client(api_key=os.environ["MAILBEAM_KEY"])

async def verify_onboarding_email(
    email: str,
    user_id: str,
    consent_given: bool,
) -> dict:
    if not consent_given:
        raise HTTPException(
            status_code=400,
            detail="GDPR consent required before email verification."
        )

    result = mb.verify(email)

    # Write audit event — hash email for GDPR data minimization
    await audit_log.write({
        "event": "email_verification",
        "user_id": user_id,
        "email_sha256": hashlib.sha256(email.lower().encode()).hexdigest(),
        "result": result.status,
        "score": result.score,
        "timestamp": datetime.utcnow().isoformat() + "Z",
        # NOTE: raw email is NOT stored in audit log
    })

    if not result.valid:
        raise HTTPException(
            status_code=422,
            detail={
                "code": "EMAIL_INVALID",
                "message": "Email address is not reachable.",
                "suggestion": result.suggestion,
            }
        )

    if result.role:
        raise HTTPException(
            status_code=422,
            detail={
                "code": "ROLE_EMAIL",
                "message": "Please use a personal email address, not a shared inbox.",
            }
        )

    return {"verified": True, "score": result.score}