diff --git a/backend/app/__init__.py b/backend/app/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/backend/app/api/__init__.py b/backend/app/api/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/backend/app/api/router.py b/backend/app/api/router.py
new file mode 100644
index 000000000..5bd5e0c85
--- /dev/null
+++ b/backend/app/api/router.py
@@ -0,0 +1,12 @@
+"""API router aggregator — mounts the email-notification endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from app.api.v1.endpoints import notifications, webhooks
+
+api_router = APIRouter()
+
+api_router.include_router(notifications.router, prefix="/notifications", tags=["notifications"])
+api_router.include_router(webhooks.router, prefix="/webhooks", tags=["webhooks"])
\ No newline at end of file
diff --git a/backend/app/api/v1/__init__.py b/backend/app/api/v1/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/backend/app/api/v1/endpoints/__init__.py b/backend/app/api/v1/endpoints/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/backend/app/api/v1/endpoints/notifications.py b/backend/app/api/v1/endpoints/notifications.py
new file mode 100644
index 000000000..685eec54c
--- /dev/null
+++ b/backend/app/api/v1/endpoints/notifications.py
@@ -0,0 +1,107 @@
+"""Notification endpoints.
+
+GET /api/notifications/preferences -> preferences for a user
+PUT /api/notifications/preferences -> update preferences
+POST /api/notifications/send -> trigger a notification (test/admin)
+
+The user is identified via the ``X-User-Id`` header (or the OAuth ``sub`` claim
+when running behind the full auth stack). This keeps the notification module
+self-contained so it can be dropped into the backend without a hard dependency
+on the auth router.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Header, Response
+
+from app.email_service import email_service
+from app.models.email import (
+ PreferenceResponse,
+ PreferenceUpdate,
+ SendNotificationRequest,
+)
+from app.services.preference_store import preference_store
+
+router = APIRouter()
+
+
+def _user_id(x_user_id: str | None) -> str:
+ return x_user_id or "anonymous"
+
+
+@router.get("/preferences", response_model=PreferenceResponse)
+async def get_preferences(x_user_id: str | None = Header(default=None)):
+ user_id = _user_id(x_user_id)
+ pref = preference_store.get(user_id)
+ return PreferenceResponse(
+ email=pref.get("email"),
+ frequency=pref.get("frequency", "instant"),
+ notify_new_bounty=pref.get("notify_new_bounty", True),
+ notify_status_update=pref.get("notify_status_update", True),
+ notify_payout=pref.get("notify_payout", True),
+ digest_day=pref.get("digest_day"),
+ updated_at=None,
+ )
+
+
+@router.put("/preferences", response_model=PreferenceResponse)
+async def update_preferences(
+ body: PreferenceUpdate, x_user_id: str | None = Header(default=None)
+):
+ user_id = _user_id(x_user_id)
+ pref = preference_store.upsert(user_id, body)
+ return PreferenceResponse(
+ email=pref.get("email"),
+ frequency=pref.get("frequency", "instant"),
+ notify_new_bounty=pref.get("notify_new_bounty", True),
+ notify_status_update=pref.get("notify_status_update", True),
+ notify_payout=pref.get("notify_payout", True),
+ digest_day=pref.get("digest_day"),
+ updated_at=None,
+ )
+
+
+@router.post("/send")
+async def send_notification(body: SendNotificationRequest):
+ """Trigger a notification (used by the admin panel / test harness).
+
+ In production the bounty create/update/complete flows call
+ :func:`app.services.notify.notify_bounty_event` directly; this endpoint
+ exists for manual testing and observability.
+ """
+ if body.notification_type.value == "new_bounty":
+ await email_service.send_new_bounty_notification(
+ to=str(body.to),
+ username=body.username,
+ bounty_title=body.bounty_title,
+ bounty_tier=body.bounty_tier,
+ reward=body.reward,
+ skills=body.skills,
+ bounty_url=body.bounty_url,
+ )
+ elif body.notification_type.value == "status_update":
+ await email_service.send_status_update(
+ to=str(body.to),
+ username=body.username,
+ bounty_title=body.bounty_title,
+ status=body.status,
+ details=body.details,
+ bounty_url=body.bounty_url,
+ )
+ elif body.notification_type.value == "payout":
+ await email_service.send_payout_notification(
+ to=str(body.to),
+ username=body.username,
+ bounty_title=body.bounty_title,
+ amount=body.reward,
+ tx_url=body.tx_url,
+ )
+ else:
+ await email_service.send_weekly_digest(
+ to=str(body.to),
+ username=body.username,
+ new_bounties=body.new_bounties,
+ completed_bounties=body.completed_bounties,
+ bounties_url=body.bounty_url,
+ )
+ return Response(status_code=202)
\ No newline at end of file
diff --git a/backend/app/api/v1/endpoints/webhooks.py b/backend/app/api/v1/endpoints/webhooks.py
new file mode 100644
index 000000000..1d3b67111
--- /dev/null
+++ b/backend/app/api/v1/endpoints/webhooks.py
@@ -0,0 +1,68 @@
+"""SendGrid inbound event webhook.
+
+Receives delivery events (bounce, dropped, delivered, open, click) so the
+system can track email delivery health. The route is
+
+ POST /api/webhooks/sendgrid/events
+
+and is called by SendGrid's Event Webhook when the customer has configured
+the webhook URL in the SendGrid dashboard to point to this endpoint.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Sequence
+
+from fastapi import APIRouter, BackgroundTasks, Request
+
+from app.models.email import DeliveryEvent
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.post("/sendgrid/events")
+async def sendgrid_event_webhook(
+ request: Request,
+ background_tasks: BackgroundTasks,
+):
+ """Receive a batch of SendGrid delivery events."""
+ try:
+ events: Sequence[dict] = await request.json()
+ except Exception:
+ logger.warning("sendgrid webhook: invalid JSON body")
+ return {"status": "accepted"}
+
+ background_tasks.add_task(_process_events, events)
+ return {"status": "accepted"}
+
+
+def _process_events(events: Sequence[dict]) -> None:
+ """Process delivery events in the background."""
+ for raw in events:
+ try:
+ event = DeliveryEvent(**raw)
+ except Exception:
+ logger.debug("sendgrid webhook: skipping invalid event %s", raw)
+ continue
+
+ if event.event in ("bounce", "dropped"):
+ logger.warning(
+ "email %s event=%s email=%s reason=%s status=%s",
+ event.sg_message_id,
+ event.event,
+ event.email,
+ event.reason,
+ event.status,
+ )
+ elif event.event in ("delivered", "open", "click"):
+ logger.debug(
+ "email %s event=%s email=%s",
+ event.sg_message_id,
+ event.event,
+ event.email,
+ )
+ else:
+ logger.debug("email event=%s email=%s", event.event, event.email)
\ No newline at end of file
diff --git a/backend/app/email_service.py b/backend/app/email_service.py
new file mode 100644
index 000000000..96d3ef04f
--- /dev/null
+++ b/backend/app/email_service.py
@@ -0,0 +1,142 @@
+"""Email notification service for SolFoundry bounty updates.
+
+Sends notifications via SendGrid when configured, otherwise falls back to
+logging the outbound email (development mode). Uses httpx (already a
+backend dependency) for the SendGrid REST API.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional, Sequence
+
+import httpx
+
+from app.email_templates import (
+ bounty_status_email,
+ digest_email,
+ new_bounty_email,
+ payout_email,
+)
+
+logger = logging.getLogger(__name__)
+
+SENDGRID_API_URL = "https://api.sendgrid.com/v3/mail/send"
+
+
+class EmailService:
+ """Sends HTML email via SendGrid (or logs in dev mode)."""
+
+ def __init__(self) -> None:
+ self.from_email = os.getenv("FROM_EMAIL", "noreply@solfoundry.xyz")
+ self.api_key = os.getenv("SENDGRID_API_KEY", "")
+
+ @property
+ def enabled(self) -> bool:
+ return bool(self.api_key)
+
+ async def send_email(
+ self,
+ to: str,
+ subject: str,
+ html_body: str,
+ tracking_id: Optional[str] = None,
+ ) -> bool:
+ """Deliver an HTML email. Returns True on success (or dev-mode log)."""
+ if not self.enabled:
+ logger.info("[DEV] email to=%s subject=%s", to, subject)
+ return True
+
+ payload = {
+ "personalizations": [{"to": [{"email": to}]}],
+ "from": {"email": self.from_email, "name": "SolFoundry"},
+ "subject": subject,
+ "content": [{"type": "text/html", "value": html_body}],
+ }
+ if tracking_id:
+ payload["custom_args"] = {"tracking_id": tracking_id}
+
+ try:
+ async with httpx.AsyncClient(timeout=15.0) as client:
+ resp = await client.post(
+ SENDGRID_API_URL,
+ headers={
+ "Authorization": f"Bearer {self.api_key}",
+ "Content-Type": "application/json",
+ },
+ json=payload,
+ )
+ if resp.status_code in (200, 202):
+ logger.info("sent email to=%s tracking=%s", to, tracking_id)
+ return True
+ logger.error(
+ "sendgrid error status=%s body=%s", resp.status_code, resp.text
+ )
+ return False
+ except httpx.HTTPError as exc:
+ logger.error("failed to send email to=%s: %s", to, exc)
+ return False
+
+ async def send_new_bounty_notification(
+ self,
+ to: str,
+ username: str,
+ bounty_title: str,
+ bounty_tier: str,
+ reward: str,
+ skills: Sequence[str],
+ bounty_url: str,
+ tracking_id: Optional[str] = None,
+ ) -> bool:
+ html = new_bounty_email(username, bounty_title, bounty_tier, reward, skills, bounty_url)
+ return await self.send_email(
+ to, f"🔨 New Bounty: {bounty_title}", html, tracking_id=tracking_id
+ )
+
+ async def send_status_update(
+ self,
+ to: str,
+ username: str,
+ bounty_title: str,
+ status: str,
+ details: str,
+ bounty_url: str,
+ tracking_id: Optional[str] = None,
+ ) -> bool:
+ html = bounty_status_email(username, bounty_title, status, details, bounty_url)
+ return await self.send_email(
+ to, f"📋 Update: {bounty_title}", html, tracking_id=tracking_id
+ )
+
+ async def send_payout_notification(
+ self,
+ to: str,
+ username: str,
+ bounty_title: str,
+ amount: str,
+ tx_url: str,
+ tracking_id: Optional[str] = None,
+ ) -> bool:
+ html = payout_email(username, bounty_title, amount, tx_url)
+ return await self.send_email(
+ to, f"💰 Payout: {amount}", html, tracking_id=tracking_id
+ )
+
+ async def send_weekly_digest(
+ self,
+ to: str,
+ username: str,
+ new_bounties: Sequence[dict],
+ completed_bounties: Sequence[dict],
+ bounties_url: str,
+ digest_type: str = "weekly",
+ tracking_id: Optional[str] = None,
+ ) -> bool:
+ html = digest_email(username, new_bounties, completed_bounties, bounties_url, digest_type)
+ return await self.send_email(
+ to, f"📊 {digest_type.title()} Digest", html, tracking_id=tracking_id
+ )
+
+
+email_service = EmailService()
\ No newline at end of file
diff --git a/backend/app/email_templates.py b/backend/app/email_templates.py
new file mode 100644
index 000000000..4eee8c7a5
--- /dev/null
+++ b/backend/app/email_templates.py
@@ -0,0 +1,216 @@
+"""HTML email templates for SolFoundry bounty notifications.
+
+Each function returns a full HTML string ready to be sent via SendGrid
+or the local dev fallback.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+_BASE_STYLES = """
+
+"""
+
+
+def _wrap(title: str, body: str, unsubscribe_token: str | None = None) -> str:
+ unsubscribe = ""
+ if unsubscribe_token:
+ unsubscribe = (
+ f''
+ f'Unsubscribe from these emails
'
+ )
+ return f"""
+
+{_BASE_STYLES}
+
+
+
+ {body}
+
+
+
+"""
+
+
+def new_bounty_email(
+ username: str,
+ bounty_title: str,
+ bounty_tier: str,
+ reward: str,
+ skills: Sequence[str],
+ bounty_url: str,
+) -> str:
+ """Email template for a new bounty notification."""
+ tier_class = {"t1": "badge-t1", "t2": "badge-t2", "t3": "badge-t3"}.get(
+ bounty_tier.lower(), "badge-t2"
+ )
+ skills_html = "".join(
+ f'{s}' for s in skills
+ ) if skills else ""
+
+ body = f"""
+
+
Hey {username},
+
A new bounty matching your interests has been posted!
+
{bounty_title}
+
+ {bounty_tier.upper()}
+ {reward}
+
+ {f'
{skills_html}
' if skills_html else ""}
+
+ View Bounty
+
+
+
Hey {username},
+
Your submission for {bounty_title} has been updated:
+
+ {status_icon} {status.replace("_", " ").title()}
+
+
{details}
+
+ View Submission
+
+
+
💰
+
Hey {username},
+
Your bounty {bounty_title} has been paid out!
+
{amount}
+
Transaction on Solana
+
+ View Transaction
+
+
'
+ f'🆕 New Bounties ({len(new_bounties)})
'
+ )
+ for b in new_bounties:
+ tier_class = {"t1": "badge-t1", "t2": "badge-t2", "t3": "badge-t3"}.get(
+ b.get("tier", "t2").lower(), "badge-t2"
+ )
+ lines.append(
+ f''
+ f'
'
+ f'{b["title"]}'
+ f'
'
+ f'{b.get("tier", "T2").upper()}'
+ f'{b["reward"]}'
+ f''
+ f'✅ Completed Bounties ({len(completed_bounties)})
'
+ )
+ for b in completed_bounties:
+ lines.append(
+ f''
+ )
+
+ bounty_list = "".join(lines) if lines else (
+ 'No activity in the past period.
'
+ )
+
+ body = f"""
+
+
Hey {username},
+
Here's your {digest_type} digest from SolFoundry!
+ {bounty_list}
+
+ Browse All Bounties
+
+
hi
")
+ assert ok is True
+
+ @pytest.mark.asyncio
+ async def test_sendgrid_success(self):
+ svc = EmailService()
+ svc.api_key = "test-key"
+ assert svc.enabled is True
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_post = AsyncMock()
+ mock_post.return_value.status_code = 202
+ mock_client.return_value.__aenter__.return_value.post = mock_post
+
+ ok = await svc.send_email(to="test@example.com", subject="Test", html_body="hi
")
+ assert ok is True
+ mock_post.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_sendgrid_failure(self):
+ svc = EmailService()
+ svc.api_key = "test-key"
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_post = AsyncMock()
+ mock_post.return_value.status_code = 401
+ mock_client.return_value.__aenter__.return_value.post = mock_post
+
+ ok = await svc.send_email(to="test@example.com", subject="Test", html_body="hi
")
+ assert ok is False
+
+
+class TestPreferenceStore:
+ """Verify the persistent preference store."""
+
+ def test_default_preference(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ pref = store.get("user_1")
+ assert pref["frequency"] == "instant"
+ assert pref["notify_new_bounty"] is True
+ assert pref["notify_status_update"] is True
+ assert pref["notify_payout"] is True
+
+ def test_upsert_and_retrieve(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ update = PreferenceUpdate(
+ email="test@example.com",
+ frequency=NotificationFrequency.daily,
+ notify_new_bounty=True,
+ notify_status_update=False,
+ notify_payout=True,
+ digest_day="mon",
+ )
+ stored = store.upsert("user_1", update)
+ assert stored["email"] == "test@example.com"
+ assert stored["frequency"] == "daily"
+
+ # Verify persistence by loading a new store from the same file
+ store2 = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ pref = store2.get("user_1")
+ assert pref["email"] == "test@example.com"
+ assert pref["frequency"] == "daily"
+ assert pref["notify_status_update"] is False
+
+ def test_subscribers_for(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ user1 = PreferenceUpdate(email="a@example.com", frequency=NotificationFrequency.instant)
+ user2 = PreferenceUpdate(email="b@example.com", frequency=NotificationFrequency.instant, notify_new_bounty=False)
+ store.upsert("user_a", user1)
+ store.upsert("user_b", user2)
+
+ subs = store.subscribers_for("new_bounty")
+ emails = [s["email"] for s in subs]
+ assert "a@example.com" in emails
+ assert "b@example.com" not in emails # opted out
+
+ def test_email_for_none(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ assert store.email_for("nonexistent") is None
+
+ def test_email_for(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ store.upsert("user_1", PreferenceUpdate(email="test@example.com"))
+ assert store.email_for("user_1") == "test@example.com"
+
+
+class TestNotifyService:
+ """Verify the notification orchestration layer."""
+
+ @pytest.mark.asyncio
+ async def test_unknown_event_type(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ store.upsert("user_1", PreferenceUpdate(email="test@example.com"))
+
+ sent = await notify_bounty_event(event_type="unknown", bounty_title="test", specific_user_id="user_1")
+ assert sent == 0
+
+ @pytest.mark.asyncio
+ async def test_skips_user_without_email(self, tmp_path):
+ store = PreferenceStore(path=str(tmp_path / "prefs.json"))
+ store.upsert("user_1", PreferenceUpdate(email="x@example.com"))
+ # Clear the email in the stored data to simulate unset email
+ store._data["user_1"]["email"] = ""
+ store._flush()
+
+ sent = await notify_bounty_event(event_type="new_bounty", bounty_title="test", specific_user_id="user_1")
+ assert sent == 0
+
+
+class TestSendNotificationRequest:
+ def test_defaults(self):
+ req = SendNotificationRequest(to="test@example.com")
+ assert req.notification_type == NotificationType.new_bounty
+ assert req.username == "there"
+ assert req.bounty_title == "Test Bounty"
\ No newline at end of file