UNSUBSCRIBE

[arnavs-0]

closes #135

[HangYeung1]

This provisions a new SES mailing list resource. Can we use our own database for tracking instead? It would be a cleaner source of truth. Two ideas off the top of my head:

1. Unsub links with user_id key to trigger unsub on mhacks.org route.
2. Emailing preferences setting page on mhacks.org.

Technically, (2) requires each user to have an account but I think our auth system is seamless enough that its not an issue.

[HangYeung1]

comment

[HangYeung1]

from gemini:

Here is a complete, copy-pasteable summary of the architecture and workflow for handling AWS SMS and SES events in a Next.js application.

---

AWS SMS & SES Event Webhook Workflow (Next.js)

This workflow centralizes all communication events (SMS replies, SMS opt-outs, email bounces, and email unsubscribes) into a single Next.js webhook powered by Amazon SNS.

Phase 1: The Next.js Webhook (The Event Hub)

You need a single public endpoint to receive, verify, and process all event payloads from AWS.

1. Install Dependencies: Run npm install sns-validator to cryptographically verify that inbound requests actually originate from AWS.
2. Create the Route: Create app/api/sns/route.ts.
3. Handle Handshakes: If the header x-amz-sns-message-type is SubscriptionConfirmation, automatically fetch() the SubscribeURL provided in the payload to prove you own the endpoint.
4. Process Notifications: If the type is Notification, parse message.Message to read the actual event data (SMS reply, email bounce, unsubscription, etc.) and update your database. Return a 200 OK within 15 seconds.

Phase 2: AWS SNS Setup (The Router)

SNS acts as the middleman between your communication services (SMS/SES) and your Next.js application.

1. Create a Topic: In the AWS SNS console, create a standard topic (e.g., CommunicationsWebhookTopic).
2. Create a Subscription: Subscribe your Next.js endpoint ([https://yourdomain.com/api/sns](https://yourdomain.com/api/sns)) to this topic using the HTTPS protocol. AWS will instantly ping your endpoint to confirm it.

Phase 3: AWS SMS & Two-Way Routing

Configure your SMS resources and tell AWS to route inbound messages/opt-outs to your SNS topic.

1. Core SMS Setup: In the AWS End User Messaging console, create a Phone Pool, verify a destination number (if in the sandbox), and set up a Protect Configuration to prevent toll fraud.
2. Route Inbound Messages: Set up two-way SMS on your origination identity and point the inbound destination to your SNS topic.
3. Handle STOP Requests:

• Default: AWS automatically intercepts "STOP" and blocks future sends.
• Self-Managed: Enable self-managed opt-outs to route "STOP" messages directly to your Next.js webhook via SNS, making you responsible for updating your database.

Phase 4: AWS SES Email Events & Unsubscribes

Configure SES to push delivery stats and unsubscriptions to your SNS topic.

1. Create an SES Configuration Set: In the SES console, create a Configuration Set (e.g., WebhookConfigSet).
2. Add Event Destinations: Within that set, point the destination to your SNS topic. Check the boxes for Sends, Deliveries, Bounces, Clicks, and Subscriptions.
3. Include Tracking on Send: When sending an email via the AWS SDK, pass the ConfigurationSetName so SES knows to track it.
4. Handle Unsubscribes:

• Pass ListManagementOptions (Contact List and Topic) when sending the email.
• Include {{amazonSESUnsubscribeUrl}} in your email body.
• When a user clicks it, SES updates their AWS-hosted status and fires an eventType: "Subscription" payload to your Next.js webhook, detailing the newTopicPreferences (OPT_OUT).

---

Would you like me to generate a sample database schema (e.g., Prisma or SQL) for storing these user preferences, bounces, and opt-outs?

[arnavs-0]

works in test but no clue about prod. check the md doc for more info. This needs a SecureString in AWS