An open source, non-profit web search engine
Add marketing email opt-in with GDPR-aligned consent tracking
Daoud Clarke862bc0f49b80
diff --git a/mwmbl/admin.py b/mwmbl/admin.pyindex 42b0dc5..214a21f 100644--- a/mwmbl/admin.py+++ b/mwmbl/admin.py@@ -3,7 +3,7 @@ from django.contrib import adminfrom django.contrib.admin import ModelAdminfrom django.contrib.auth.admin import UserAdmin-from mwmbl.models import MwmblUser, OldIndex, Curation, FlagCuration, DomainSubmission, ApiKey, generate_api_key+from mwmbl.models import MwmblUser, OldIndex, Curation, FlagCuration, DomainSubmission, ApiKey, MarketingConsent, generate_api_keyclass ApiKeyForm(forms.ModelForm):@@ -50,4 +50,11 @@ admin.site.register(Curation, ModelAdmin)admin.site.register(OldIndex, ModelAdmin)admin.site.register(FlagCuration, ModelAdmin)admin.site.register(DomainSubmission, ModelAdmin)+class MarketingConsentAdmin(ModelAdmin):+ list_display = ("user", "source", "opted_in", "timestamp")+ list_filter = ("source", "opted_in")+ readonly_fields = ("user", "source", "opted_in", "timestamp")++admin.site.register(ApiKey, ApiKeyAdmin)+admin.site.register(MarketingConsent, MarketingConsentAdmin)diff --git a/mwmbl/migrations/0024_marketingconsent.py b/mwmbl/migrations/0024_marketingconsent.pynew file mode 100644index 0000000..fcae3b4--- /dev/null+++ b/mwmbl/migrations/0024_marketingconsent.py@@ -0,0 +1,28 @@+# Generated by Django 5.2.13 on 2026-06-25 07:21++import django.db.models.deletion+from django.conf import settings+from django.db import migrations, models+++class Migration(migrations.Migration):++ dependencies = [+ ('mwmbl', '0023_userbilling_cancel_at_period_end'),+ ]++ operations = [+ migrations.CreateModel(+ name='MarketingConsent',+ fields=[+ ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),+ ('source', models.CharField(choices=[('GUI', 'Consumer site (mwmbl.org)'), ('API', 'Developer site (developer.mwmbl.org)')], max_length=10)),+ ('opted_in', models.BooleanField()),+ ('timestamp', models.DateTimeField(auto_now_add=True)),+ ('user', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='marketing_consents', to=settings.AUTH_USER_MODEL)),+ ],+ options={+ 'indexes': [models.Index(fields=['user', 'source', '-timestamp'], name='mwmbl_marke_user_id_c00b4e_idx')],+ },+ ),+ ]diff --git a/mwmbl/models.py b/mwmbl/models.pyindex 32e38a1..169abcd 100644--- a/mwmbl/models.py+++ b/mwmbl/models.py@@ -208,6 +208,33 @@ class UserAgreement(models.Model):]+class MarketingSource(models.TextChoices):+ GUI = "GUI", "Consumer site (mwmbl.org)"+ API = "API", "Developer site (developer.mwmbl.org)"+++class MarketingConsent(models.Model):+ """+ Append-only audit trail of marketing email consent decisions.++ Every opt-in and opt-out writes a new row; the current state for a source is+ the `opted_in` of the latest row. Mirrors UserAgreement.+ """+ # SET_NULL (not CASCADE) so the consent proof survives account deletion,+ # matching UserAgreement.+ user = models.ForeignKey(+ MwmblUser, on_delete=models.SET_NULL, null=True, related_name="marketing_consents"+ )+ source = models.CharField(max_length=10, choices=MarketingSource.choices)+ opted_in = models.BooleanField()+ timestamp = models.DateTimeField(auto_now_add=True)++ class Meta:+ indexes = [+ models.Index(fields=["user", "source", "-timestamp"]),+ ]++class SearchResultVote(models.Model):VOTE_TYPES = {"upvote": "User upvoted this result",diff --git a/mwmbl/platform/api.py b/mwmbl/platform/api.pyindex 05cb314..e00d086 100644--- a/mwmbl/platform/api.py+++ b/mwmbl/platform/api.py@@ -4,6 +4,8 @@ from allauth.account.adapter import get_adapterfrom allauth.account.models import EmailConfirmationHMACfrom allauth.account.utils import setup_user_email, send_email_confirmationfrom django.conf import settings+from django.core import signing+from django.http import HttpResponsefrom django.utils import timezonefrom ninja import Routerfrom ninja.pagination import paginate@@ -15,7 +17,7 @@ from polar_sdk.webhooks import validate_event, WebhookVerificationErrorfrom mwmbl.exceptions import InvalidRequestfrom mwmbl.search_auth import invalidate_api_key_cache, invalidate_user_api_key_cache-from mwmbl.models import AgreementType, MwmblUser, DomainSubmission, SearchResultVote, ApiKey, UsageBucket, UserBilling, UserAgreement, generate_username+from mwmbl.models import AgreementType, MwmblUser, DomainSubmission, SearchResultVote, ApiKey, UsageBucket, UserBilling, UserAgreement, MarketingConsent, MarketingSource, generate_usernamefrom mwmbl.platform.schemas import (Registration, ConfirmEmail, DomainSubmissionSchema, UpdateDomainSubmission,VoteRequest, VoteRemoveRequest, VoteStatsRequest, VoteResponse, VoteStats, UserVoteHistory,@@ -23,6 +25,7 @@ from mwmbl.platform.schemas import (UserProfileResponse, SubscriptionResponse, CheckoutRequest, CheckoutResponse, ChangePlanRequest,ForgotPasswordRequest, ResetPasswordRequest,AgreementAcceptRequest, AgreementResponse,+ MarketingConsentRequest, MarketingConsentResponse,)logger = logging.getLogger(__name__)@@ -63,6 +66,9 @@ def register(request, registration: Registration):if registration.agreements:_record_agreements(user, registration.agreements)+ if registration.source is not None:+ _record_marketing_consent(user, registration.source, registration.marketing_opt_in)+setup_user_email(request, user, [])send_email_confirmation(request, user, signup=True)@@ -360,6 +366,21 @@ def _record_agreements(user: MwmblUser, agreement_types: list) -> None:)+def _record_marketing_consent(user: MwmblUser, source: MarketingSource, opted_in: bool) -> None:+ MarketingConsent.objects.create(user=user, source=source, opted_in=opted_in)+++_UNSUBSCRIBE_SALT = "marketing-unsubscribe"+++def make_unsubscribe_token(user: MwmblUser, source: MarketingSource) -> str:+ """+ Build a signed, URL-safe token identifying a (user, source) pair for one-click+ unsubscribe. No expiry: unsubscribe links in old emails must keep working.+ """+ return signing.dumps({"user_id": user.id, "source": source}, salt=_UNSUBSCRIBE_SALT)++def _require_current_agreement(user: MwmblUser, agreement_type: AgreementType) -> None:current_version = settings.CURRENT_AGREEMENT_VERSIONS.get(agreement_type)accepted = UserAgreement.objects.filter(@@ -456,6 +477,110 @@ def get_agreement_history(request) -> list[AgreementResponse]:return UserAgreement.objects.filter(user=request.user).order_by("-accepted_at")+# ---------------------------------------------------------------------------+# Marketing consent+# ---------------------------------------------------------------------------++ "/marketing-consent",+ auth=JWTAuth(),+ response=list[MarketingConsentResponse],+ summary="Get marketing email consent",+ description=(+ "Returns the current marketing email consent state for each source the user has a "+ "record for (`GUI` = mwmbl.org, `API` = developer.mwmbl.org). The state for a source "+ "is its most recently recorded decision. Sources with no record are omitted. "+ "Requires a verified account."+ ),+ tags=["Marketing"],+)+def get_marketing_consent(request) -> list[MarketingConsentResponse]:+ check_email_verified(request)+ result = []+ for source in MarketingSource:+ latest = (+ MarketingConsent.objects.filter(user=request.user, source=source)+ .order_by("-timestamp")+ .first()+ )+ if latest:+ result.append(MarketingConsentResponse(+ source=latest.source,+ opted_in=latest.opted_in,+ timestamp=latest.timestamp,+ ))+ return result+++ "/marketing-consent",+ auth=JWTAuth(),+ response=MarketingConsentResponse,+ summary="Update marketing email consent",+ description=(+ "Record a marketing email consent decision for the authenticated user against a "+ "source. Use `opted_in=false` to withdraw consent. Each call appends a new "+ "timestamped record, preserving the full consent history. Requires a verified account."+ ),+ tags=["Marketing"],+)+def update_marketing_consent(request, body: MarketingConsentRequest):+ check_email_verified(request)+ _record_marketing_consent(request.user, body.source, body.opted_in)+ return MarketingConsentResponse(+ source=body.source,+ opted_in=body.opted_in,+ timestamp=timezone.now(),+ )+++def _unsubscribe_from_token(token: str) -> None:+ try:+ data = signing.loads(token, salt=_UNSUBSCRIBE_SALT)+ except signing.BadSignature:+ raise InvalidRequest("Invalid or malformed unsubscribe token.", status=400)+ user = MwmblUser.objects.filter(id=data["user_id"]).first()+ if user is None:+ raise InvalidRequest("Unknown user.", status=400)+ _record_marketing_consent(user, data["source"], opted_in=False)+++ "/marketing/unsubscribe",+ auth=None,+ summary="One-click unsubscribe from marketing emails",+ description=(+ "RFC 8058 one-click unsubscribe target for the `List-Unsubscribe` email header. "+ "Takes a signed `token` identifying the recipient and source — no login required. "+ "Records an opt-out and is idempotent. Mail clients POST here with the body "+ "`List-Unsubscribe=One-Click`."+ ),+ tags=["Marketing"],+)+def unsubscribe_marketing(request, token: str):+ _unsubscribe_from_token(token)+ return {"status": "ok", "message": "You have been unsubscribed from marketing emails."}+++ "/marketing/unsubscribe",+ auth=None,+ summary="One-click unsubscribe (browser-friendly)",+ description=(+ "Browser-friendly variant of the one-click unsubscribe endpoint, for users who open "+ "the `List-Unsubscribe` link directly. Records the opt-out and returns a confirmation page."+ ),+ tags=["Marketing"],+)+def unsubscribe_marketing_page(request, token: str):+ _unsubscribe_from_token(token)+ return HttpResponse(+ "<html><body><h1>You have been unsubscribed</h1>"+ "<p>You will no longer receive marketing emails from Mwmbl.</p></body></html>",+ content_type="text/html",+ )++# ---------------------------------------------------------------------------# API key management# ---------------------------------------------------------------------------diff --git a/mwmbl/platform/schemas.py b/mwmbl/platform/schemas.pyindex d26a424..1302a23 100644--- a/mwmbl/platform/schemas.py+++ b/mwmbl/platform/schemas.py@@ -2,7 +2,7 @@ from datetime import datetimefrom typing import Optional, Literalfrom ninja import Schema, ModelSchema, Field-from mwmbl.models import AgreementType, DomainSubmission+from mwmbl.models import AgreementType, DomainSubmission, MarketingSourceclass UserProfileResponse(Schema):@@ -100,6 +100,21 @@ class AgreementResponse(Schema):accepted_at: datetime = Field(description="When the agreement was accepted.")+# ---------------------------------------------------------------------------+# Marketing consent+# ---------------------------------------------------------------------------++class MarketingConsentRequest(Schema):+ source: MarketingSource = Field(description="The property the consent applies to (`GUI` or `API`).")+ opted_in: bool = Field(description="True to opt in to marketing emails, False to withdraw consent.")+++class MarketingConsentResponse(Schema):+ source: str = Field(description="The property the consent applies to.")+ opted_in: bool = Field(description="The current opt-in state for this source.")+ timestamp: datetime = Field(description="When this consent decision was recorded.")++class Registration(Schema):email: str = Field(description="Email address for the new account. Must be unique.")password: str = Field(description="Password for the new account.")@@ -118,6 +133,21 @@ class Registration(Schema):"Accepted values: `TERMS_OF_SERVICE_GUI`, `TERMS_OF_SERVICE_API`."),)+ source: Optional[MarketingSource] = Field(+ default=None,+ description=(+ "Which Mwmbl property the user signed up from (`GUI` = mwmbl.org, "+ "`API` = developer.mwmbl.org). Determines the type of marketing email. "+ "When provided, the marketing opt-in decision is recorded against this source."+ ),+ )+ marketing_opt_in: bool = Field(+ default=False,+ description=(+ "Whether the user opted in to marketing emails. Must reflect an affirmative, "+ "unticked-by-default checkbox. Only recorded when `source` is also provided."+ ),+ )class ConfirmEmail(Schema):diff --git a/test/test_marketing_consent.py b/test/test_marketing_consent.pynew file mode 100644index 0000000..9e68c83--- /dev/null+++ b/test/test_marketing_consent.py@@ -0,0 +1,154 @@+import json++import pytest+from allauth.account.models import EmailAddress+from django.contrib.auth import get_user_model+from ninja_jwt.tokens import RefreshToken++from mwmbl.models import MarketingConsent, MarketingSource+from mwmbl.platform.api import make_unsubscribe_token++User = get_user_model()++REGISTER_URL = "/api/v1/platform/register"+CONSENT_URL = "/api/v1/platform/marketing-consent"+UNSUBSCRIBE_URL = "/api/v1/platform/marketing/unsubscribe"+++def verified_user(db):+ user = User.objects.create_user(+ username="swift_falcon_379",+ email="[email protected]",+ password="correctpassword",+ )+ EmailAddress.objects.create(+ user=user, email="[email protected]", verified=True, primary=True+ )+ return user+++def access_token(verified_user):+ return str(RefreshToken.for_user(verified_user).access_token)+++def _register(client, **extra):+ body = {"email": "[email protected]", "password": "correctpassword"}+ body.update(extra)+ return client.post(REGISTER_URL, data=json.dumps(body), content_type="application/json")+++# ---------------------------------------------------------------------------+# Registration records consent+# ---------------------------------------------------------------------------++def test_register_with_opt_in_records_consent(client):+ response = _register(client, source="API", marketing_opt_in=True)+ assert response.status_code == 200+ user = User.objects.get(email="[email protected]")+ consents = MarketingConsent.objects.filter(user=user)+ assert consents.count() == 1+ consent = consents.first()+ assert consent.source == MarketingSource.API+ assert consent.opted_in is True+++def test_register_with_decline_still_records(client):+ response = _register(client, source="GUI", marketing_opt_in=False)+ assert response.status_code == 200+ user = User.objects.get(email="[email protected]")+ consent = MarketingConsent.objects.get(user=user)+ assert consent.source == MarketingSource.GUI+ assert consent.opted_in is False+++def test_register_without_source_records_nothing(client):+ response = _register(client, marketing_opt_in=True)+ assert response.status_code == 200+ user = User.objects.get(email="[email protected]")+ assert MarketingConsent.objects.filter(user=user).count() == 0+++# ---------------------------------------------------------------------------+# Authenticated view + update+# ---------------------------------------------------------------------------++def test_get_marketing_consent_returns_latest_per_source(client, verified_user, access_token):+ MarketingConsent.objects.create(user=verified_user, source=MarketingSource.API, opted_in=True)+ MarketingConsent.objects.create(user=verified_user, source=MarketingSource.API, opted_in=False)++ response = client.get(CONSENT_URL, HTTP_AUTHORIZATION=f"Bearer {access_token}")+ assert response.status_code == 200+ data = response.json()+ assert len(data) == 1+ assert data[0]["source"] == "API"+ assert data[0]["opted_in"] is False+++def test_update_marketing_consent_appends_row(client, verified_user, access_token):+ MarketingConsent.objects.create(user=verified_user, source=MarketingSource.GUI, opted_in=True)++ response = client.post(+ CONSENT_URL,+ data=json.dumps({"source": "GUI", "opted_in": False}),+ content_type="application/json",+ HTTP_AUTHORIZATION=f"Bearer {access_token}",+ )+ assert response.status_code == 200+ assert response.json()["opted_in"] is False+ # History preserved — row count grows rather than mutating in place.+ assert MarketingConsent.objects.filter(user=verified_user, source=MarketingSource.GUI).count() == 2++ # GET now reflects the withdrawal.+ latest = client.get(CONSENT_URL, HTTP_AUTHORIZATION=f"Bearer {access_token}").json()+ assert latest[0]["opted_in"] is False+++def test_marketing_consent_requires_auth(client):+ assert client.get(CONSENT_URL).status_code == 401+++# ---------------------------------------------------------------------------+# One-click unsubscribe (RFC 8058)+# ---------------------------------------------------------------------------++def test_unsubscribe_token_roundtrip_records_opt_out(client, verified_user):+ token = make_unsubscribe_token(verified_user, MarketingSource.API)+ response = client.post(f"{UNSUBSCRIBE_URL}?token={token}")+ assert response.status_code == 200+ consent = MarketingConsent.objects.get(user=verified_user, source=MarketingSource.API)+ assert consent.opted_in is False+++def test_unsubscribe_is_idempotent(client, verified_user):+ token = make_unsubscribe_token(verified_user, MarketingSource.GUI)+ client.post(f"{UNSUBSCRIBE_URL}?token={token}")+ client.post(f"{UNSUBSCRIBE_URL}?token={token}")+ consents = MarketingConsent.objects.filter(user=verified_user, source=MarketingSource.GUI)+ assert consents.count() == 2+ assert all(c.opted_in is False for c in consents)+++def test_unsubscribe_rejects_bad_token(client, verified_user):+ response = client.post(f"{UNSUBSCRIBE_URL}?token=garbage")+ assert response.status_code == 400+ assert MarketingConsent.objects.count() == 0+++def test_unsubscribe_get_renders_confirmation(client, verified_user):+ token = make_unsubscribe_token(verified_user, MarketingSource.API)+ response = client.get(f"{UNSUBSCRIBE_URL}?token={token}")+ assert response.status_code == 200+ assert b"unsubscribed" in response.content.lower()+ assert MarketingConsent.objects.filter(user=verified_user).count() == 1