Newsletter Integrations
Relevant source files
The following files were used as context for generating this wiki page:
The Newsletter Integration system in SoulSeer provides a mechanism for users to subscribe to spiritual insights and community updates. This system handles public signups, data persistence for subscribers, and integration with Brevo (formerly Sendinblue) for transactional welcome emails.
The system is split into a frontend subscription form, a backend API for managing subscriber state in the database, and a specialized service for communicating with the Brevo API. Sources: client/src/pages/HomePage.tsx:165-188, server/src/routes/newsletter.ts:1-58
System Architecture
The newsletter system follows a standard client-server-external service architecture. The frontend collects user emails, the backend validates and stores them in a PostgreSQL database using Drizzle ORM, and the BrevoService handles external email dispatch.
Subscription Data Flow
The following diagram illustrates the flow of a subscription request from the user interface through the backend to the external email provider.
This diagram shows how the system handles both new signups and re-activations of previously unsubscribed users. Sources: server/src/routes/newsletter.ts:16-52, client/src/pages/HomePage.tsx:88-109
Backend Implementation
API Endpoints
The backend exposes a dedicated router for newsletter operations, mounted at /api/newsletter. Sources: server/src/index.ts:117-118
| Method | Endpoint | Description | Validation |
|---|---|---|---|
POST | /subscribe | Adds a new email to the subscriber list or re-activates an existing one. | Email (Zod) |
POST | /unsubscribe | Sets the unsubscribedAt timestamp for a given email. | Email (Zod) |
Sources: server/src/routes/newsletter.ts:16-64
Data Persistence
Subscribers are stored in the newsletterSubscribers table. The subscription logic includes a "fire-and-forget" call to the welcome email service to ensure HTTP responses are not blocked by external API latency. Sources: server/src/routes/newsletter.ts:31-33, server/src/routes/newsletter.ts:46-48
Brevo Email Service
The BrevoService is a thin wrapper around the Brevo Transactional Email API. It uses the native fetch API to send requests to https://api.brevo.com/v3/smtp/email. Sources: server/src/services/brevo-service.ts:39-44
Configuration
The service behavior is governed by environment variables defined in the central config.
| Option | Key | Description |
|---|---|---|
apiKey | BREVO_API_KEY | Authentication key for Brevo API. |
senderEmail | BREVO_SENDER_EMAIL | Default: hello@soulseerpsychics.com. |
senderName | BREVO_SENDER_NAME | Default: SoulSeer. |
welcomeEnabled | NEWSLETTER_WELCOME_ENABLED | Controls the sendNewsletterWelcome trigger. |
Sources: server/src/config.ts:69-72, server/src/config.ts:121-127
Welcome Email Sequence
When a user subscribes, the system triggers a welcome email containing themed HTML content.
The welcome email includes high-level branding and an unsubscribe link formatted as https://soulseerpsychics.com/unsubscribe?email=.... Sources: server/src/services/brevo-service.ts:31-75, server/src/services/brevo-service.ts:101-103
Frontend Integration
The newsletter signup is primarily located in the HomePage component. It utilizes a useToast hook to provide feedback to the user upon successful subscription or error.
Implementation Details
- Email Normalization: The backend transforms emails to lowercase and trims whitespace via Zod. Sources: server/src/routes/newsletter.ts:12-14
- UI State: The form tracks a
submittingstate to disable the button during API calls. Sources: client/src/pages/HomePage.tsx:86-113 - Error Handling: Standard errors include "Please enter a valid email address" or server-side rejection messages. Sources: client/src/pages/HomePage.tsx:90-93
// From client/src/pages/HomePage.tsx:165-188
<form className="newsletter" onSubmit={handleNewsletter}>
<input
type="email"
className="form-input"
placeholder="Enter your email address"
value={email}
onChange={(e) => setEmail(e.target.value)}
aria-label="Email address for newsletter"
required
/>
<Button
type="submit"
variant="gold"
loading={submitting}
disabled={submitting}
>
Subscribe
</Button>
</form>
Sources: client/src/pages/HomePage.tsx:165-188
Conclusion
The Newsletter Integration module provides an automated bridge between user interest on the landing page and community engagement. By utilizing a dedicated service for Brevo and a normalized database schema for subscribers, the platform ensures reliable data collection and professional communication while maintaining non-blocking performance for end users.