Subscription Preferences Widget
The Subscription Preferences Widget is an embeddable component that allows your users to manage their email subscription preferences without leaving your website. Users can subscribe/unsubscribe from email lists, cancel active sequences, and globally opt-out of all communications.Preview
Here’s what the widget looks like when embedded in your application:
- Email preferences header with the subscriber’s masked email address
- Email Lists section with toggles for each list the subscriber belongs to
- Active Sequences section showing any running automations with start dates
- Save preferences button to submit changes
- Global unsubscribe link to opt-out of all communications
Features
List Management
Users can toggle subscriptions to individual email lists
Sequence Control
Cancel active email sequences (automations) at any time
Global Unsubscribe
One-click option to opt-out of all communications
Auto-Resize
Widget automatically adjusts height based on content
How It Works
The widget integration consists of two parts:- Backend: Call the Sequenzy API to get a signed token for the logged-in user
- Frontend: Embed an iframe with the token to display the preferences UI
Quick Start
Step 1: Get an API Key
Navigate to Settings → API Keys in your Sequenzy dashboard to create an API key.Step 2: Backend - Get Token
Create a server-side endpoint that fetches an embed token from Sequenzy:Step 3: Frontend - Embed the Widget
Fetch the token from your backend and render the iframe:Auto-Resize
The widget automatically sends resize messages when its content height changes. Add this listener to your page to automatically adjust the iframe height:Widget Sections
The widget displays the following sections based on the subscriber’s data:Email Lists
Shows all email lists the subscriber is associated with. Each list has a toggle to subscribe or unsubscribe.Active Sequences
If the subscriber is currently in any automated email sequences, they’ll see a list of active sequences with the option to cancel each one.Global Unsubscribe
A prominent button at the bottom allows users to opt-out of all communications at once.Styling
The widget uses a clean, minimal design that works well in most applications. The “Powered by Sequenzy” footer is shown for free tier accounts and can be removed by upgrading to a paid plan.Error Handling
The token endpoint returns specific error codes to help you handle edge cases:| Status | Error Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid email format |
| 401 | UNAUTHORIZED | Invalid or missing API key |
| 404 | NOT_FOUND | Subscriber not found in Sequenzy |
| 500 | SERVER_ERROR | Server configuration error |
Best Practices
- Add to account settings: Place the widget in your user’s account or settings page
- Handle loading states: Show a spinner while fetching the token
- Handle errors gracefully: Display a friendly message if the widget fails to load
- Use auto-resize: Implement the resize handler to prevent scrollbars
- Secure your endpoint: Ensure only authenticated users can request tokens