Merge pull request #23 from adab-tech/claude/globalopportunities-deploy-yukhn1

Author: adab-tech

backend/.env.example

@@ -17,11 +17,12 @@ MAX_RETRIES=3
 RSS_MAX_ENTRIES_PER_FEED=25
 
 # ── Email alerts (optional) ──────────────────────────────────
-# Leave both unset to log emails instead of sending them (see
-# app/services/email_sender.py). Set one to send for real — if both
-# are set, Resend takes priority.
+# Leave all unset to log emails instead of sending them (see
+# app/services/email_sender.py). Set one to send for real — if more
+# than one is set, Resend takes priority, then Brevo.
 # RESEND_API_KEY=your_resend_api_key_here
 # BREVO_API_KEY=your_brevo_api_key_here
+# SENDGRID_API_KEY=your_sendgrid_api_key_here
 # ALERT_FROM_EMAIL=Global Opportunities <alerts@yourdomain.com>
 
 # ── Deployment ──────────────────────────────────────────────

backend/app/config.py

@@ -43,15 +43,17 @@ def normalize_database_url(cls, value):
     ENABLE_SCHEDULER: bool = True
     CORS_ORIGINS: str = "*"
 
-    # Email alerts — with neither key set, emails are logged, not
+    # Email alerts — with none of these keys set, emails are logged, not
     # actually sent (see app/services/email_sender.py). Set one of
-    # RESEND_API_KEY or BREVO_API_KEY to send for real; if both are set,
-    # Resend takes priority. PUBLIC_BASE_URL is used to build the
-    # manage-your-alerts link in outgoing emails. Left unset by default
-    # so it always reflects the actual API_PORT in local dev; set it
-    # explicitly in production (e.g. your Render URL).
+    # RESEND_API_KEY, BREVO_API_KEY, or SENDGRID_API_KEY to send for
+    # real; if more than one is set, Resend takes priority, then Brevo.
+    # PUBLIC_BASE_URL is used to build the manage-your-alerts link in
+    # outgoing emails. Left unset by default so it always reflects the
+    # actual API_PORT in local dev; set it explicitly in production
+    # (e.g. your Render URL).
     RESEND_API_KEY: str | None = None
     BREVO_API_KEY: str | None = None
+    SENDGRID_API_KEY: str | None = None
     ALERT_FROM_EMAIL: str = "Global Opportunities <alerts@globalopportunities.app>"
     PUBLIC_BASE_URL: str | None = None
     ALERT_DIGEST_INTERVAL_HOURS: int = 168  # weekly

backend/app/services/email_sender.py

@@ -3,8 +3,9 @@
 No email provider is required to run this app. By default, emails are
 logged (ConsoleEmailSender) so every code path — save/alert signup,
 manage links, weekly digests — works end-to-end with zero setup. Set
-RESEND_API_KEY or BREVO_API_KEY to switch to real delivery via Resend
-(https://resend.com) or Brevo (https://brevo.com) with no code changes.
+RESEND_API_KEY, BREVO_API_KEY, or SENDGRID_API_KEY to switch to real
+delivery via Resend (https://resend.com), Brevo (https://brevo.com), or
+SendGrid (https://sendgrid.com) with no code changes.
 """
 
 import logging
@@ -118,9 +119,47 @@ def send(self, message: EmailMessage) -> bool:
             return False
 
 
+class SendGridEmailSender(EmailSender):
+    """Delivers via the SendGrid v3 Mail Send API
+    (https://docs.sendgrid.com/api-reference/mail-send/mail-send)."""
+
+    _ENDPOINT = "https://api.sendgrid.com/v3/mail/send"
+
+    def __init__(self, api_key: str, from_address: str):
+        self._api_key = api_key
+        # Same split as Brevo: SendGrid wants {email, name} rather than
+        # Resend's combined "Name <email>" string.
+        name, email = parseaddr(from_address)
+        self._from = {"email": email, "name": name} if name else {"email": email}
+
+    def send(self, message: EmailMessage) -> bool:
+        try:
+            response = requests.post(
+                self._ENDPOINT,
+                headers={"Authorization": f"Bearer {self._api_key}"},
+                json={
+                    "personalizations": [{"to": [{"email": message.to}]}],
+                    "from": self._from,
+                    "subject": message.subject,
+                    "content": [
+                        {"type": "text/plain", "value": message.text_body},
+                        {"type": "text/html", "value": message.html_body},
+                    ],
+                },
+                timeout=10,
+            )
+            response.raise_for_status()
+            return True
+        except requests.RequestException as exc:
+            logger.error("SendGrid email send failed for %s: %s", message.to, exc)
+            return False
+
+
 def get_email_sender() -> EmailSender:
     if settings.RESEND_API_KEY:
         return ResendEmailSender(settings.RESEND_API_KEY, settings.ALERT_FROM_EMAIL)
     if settings.BREVO_API_KEY:
         return BrevoEmailSender(settings.BREVO_API_KEY, settings.ALERT_FROM_EMAIL)
+    if settings.SENDGRID_API_KEY:
+        return SendGridEmailSender(settings.SENDGRID_API_KEY, settings.ALERT_FROM_EMAIL)
     return ConsoleEmailSender()

backend/tests/test_email_sender.py

@@ -1,5 +1,6 @@
 """Regression tests for app/services/email_sender.py's provider senders
-and get_email_sender()'s selection priority (Resend > Brevo > console)."""
+and get_email_sender()'s selection priority (Resend > Brevo > SendGrid >
+console)."""
 
 from unittest.mock import MagicMock, patch
 
@@ -10,6 +11,7 @@
     ConsoleEmailSender,
     EmailMessage,
     ResendEmailSender,
+    SendGridEmailSender,
     get_email_sender,
 )
 
@@ -80,23 +82,81 @@ def test_send_returns_false_on_request_failure(self):
             assert sender.send(_MESSAGE) is False
 
 
+class TestSendGridEmailSender:
+    def test_send_posts_expected_payload_with_split_sender(self):
+        sender = SendGridEmailSender(
+            "fake-sendgrid-key", "Global Opportunities <alerts@globalopportunities.app>"
+        )
+        mock_response = MagicMock()
+        mock_response.raise_for_status.return_value = None
+
+        with patch("app.services.email_sender.requests.post", return_value=mock_response) as mock_post:
+            assert sender.send(_MESSAGE) is True
+
+        _, kwargs = mock_post.call_args
+        assert kwargs["headers"]["Authorization"] == "Bearer fake-sendgrid-key"
+        assert kwargs["json"]["personalizations"] == [{"to": [{"email": "subscriber@example.org"}]}]
+        assert kwargs["json"]["from"] == {
+            "email": "alerts@globalopportunities.app",
+            "name": "Global Opportunities",
+        }
+        assert kwargs["json"]["subject"] == "New matches this week"
+        assert {"type": "text/plain", "value": "hi"} in kwargs["json"]["content"]
+        assert {"type": "text/html", "value": "<p>hi</p>"} in kwargs["json"]["content"]
+
+    def test_sender_without_a_display_name_omits_name_field(self):
+        sender = SendGridEmailSender("fake-sendgrid-key", "alerts@globalopportunities.app")
+        mock_response = MagicMock()
+        mock_response.raise_for_status.return_value = None
+
+        with patch("app.services.email_sender.requests.post", return_value=mock_response) as mock_post:
+            sender.send(_MESSAGE)
+
+        _, kwargs = mock_post.call_args
+        assert kwargs["json"]["from"] == {"email": "alerts@globalopportunities.app"}
+
+    def test_send_returns_false_on_request_failure(self):
+        sender = SendGridEmailSender("fake-sendgrid-key", "alerts@globalopportunities.app")
+        with patch("app.services.email_sender.requests.post", side_effect=requests.RequestException("boom")):
+            assert sender.send(_MESSAGE) is False
+
+
 class TestGetEmailSender:
     def test_defaults_to_console_when_no_key_configured(self):
         with patch("app.services.email_sender.settings") as mock_settings:
             mock_settings.RESEND_API_KEY = None
             mock_settings.BREVO_API_KEY = None
+            mock_settings.SENDGRID_API_KEY = None
             assert isinstance(get_email_sender(), ConsoleEmailSender)
 
     def test_uses_brevo_when_only_brevo_key_set(self):
         with patch("app.services.email_sender.settings") as mock_settings:
             mock_settings.RESEND_API_KEY = None
             mock_settings.BREVO_API_KEY = "fake-brevo-key"
+            mock_settings.SENDGRID_API_KEY = None
             mock_settings.ALERT_FROM_EMAIL = "alerts@globalopportunities.app"
             assert isinstance(get_email_sender(), BrevoEmailSender)
 
-    def test_resend_takes_priority_when_both_keys_set(self):
+    def test_uses_sendgrid_when_only_sendgrid_key_set(self):
+        with patch("app.services.email_sender.settings") as mock_settings:
+            mock_settings.RESEND_API_KEY = None
+            mock_settings.BREVO_API_KEY = None
+            mock_settings.SENDGRID_API_KEY = "fake-sendgrid-key"
+            mock_settings.ALERT_FROM_EMAIL = "alerts@globalopportunities.app"
+            assert isinstance(get_email_sender(), SendGridEmailSender)
+
+    def test_resend_takes_priority_over_brevo_and_sendgrid(self):
         with patch("app.services.email_sender.settings") as mock_settings:
             mock_settings.RESEND_API_KEY = "fake-resend-key"
             mock_settings.BREVO_API_KEY = "fake-brevo-key"
+            mock_settings.SENDGRID_API_KEY = "fake-sendgrid-key"
             mock_settings.ALERT_FROM_EMAIL = "alerts@globalopportunities.app"
             assert isinstance(get_email_sender(), ResendEmailSender)
+
+    def test_brevo_takes_priority_over_sendgrid(self):
+        with patch("app.services.email_sender.settings") as mock_settings:
+            mock_settings.RESEND_API_KEY = None
+            mock_settings.BREVO_API_KEY = "fake-brevo-key"
+            mock_settings.SENDGRID_API_KEY = "fake-sendgrid-key"
+            mock_settings.ALERT_FROM_EMAIL = "alerts@globalopportunities.app"
+            assert isinstance(get_email_sender(), BrevoEmailSender)

docs/DEPLOY.md

@@ -84,7 +84,7 @@ Copy `backend/.env.example` to `backend/.env` for local dev.
 | `CORS_ORIGINS` | Comma-separated origins, or `*` |
 | `PORT` | Set by Fly/Railway/Render (uvicorn listens here) |
 | `GOOGLE_API_KEY` / `GOOGLE_CSE_ID` | Optional; improves discovery |
-| `RESEND_API_KEY` / `BREVO_API_KEY` | Optional; unset means alert/save-confirmation emails are logged, not sent. If both are set, Resend takes priority. |
+| `RESEND_API_KEY` / `BREVO_API_KEY` / `SENDGRID_API_KEY` | Optional; unset means alert/save-confirmation emails are logged, not sent. If more than one is set, Resend takes priority, then Brevo. |
 
 ## Health check