Email Routing & SMTP Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Email Routing & SMTP Configuration system manages all transactional outbound communications for PuppyPad. This module handles critical workflows including account verification, password resets, administrative abuse reports, and community notifications for follows, likes, and comments.
The system relies on an external transactional SMTP provider and specific DNS records to ensure email deliverability and domain reputation. When SMTP is not configured, the application logs email contents to the console for development and testing purposes.
Sources: src/server.js:44-59, PLAN.md:2.7, test/app.test.js:15-20
Architecture and SMTP Transport
PuppyPad uses the nodemailer library to establish a connection with a transactional SMTP server. The application creates a transport object based on environment variables. If SMTP_HOST is absent, the system defaults to a null mailer, which triggers console logging instead of actual delivery.
Mailer Configuration Logic
The transport supports both standard SMTP (port 587 with STARTTLS) and legacy SMTPS (port 465).
The application initializes the mailer using a nodemailer.createTransport call that checks for SMTP_USER and SMTP_PASS for authentication.
Sources: src/server.js:44-51, package.json:16
Configuration Parameters
| Variable | Description | Default Value |
|---|---|---|
SMTP_HOST | Hostname of the transactional SMTP provider. | Required for mail |
SMTP_PORT | Port for SMTP connection (e.g., 587 or 465). | 587 |
SMTP_USER | Username for SMTP authentication. | Optional |
SMTP_PASS | Password for SMTP authentication. | Optional |
MAIL_FROM | The sender address used in the From header. | PuppyPad <noreply@{BASE_HOST}> |
ABUSE_EMAIL | Destination for system alerts and abuse reports. | abuse@{BASE_HOST} |
Sources: src/server.js:20-53
Email Delivery Workflows
Transactional emails are triggered by specific user actions or system events. The sendMail(to, subject, text) function acts as the central wrapper for all delivery attempts.
Core Email Triggers
- Account Verification: Triggered during signup or when an unconfirmed user attempts to log in. The email contains a signed token link valid for 48 hours.
- Password Reset: Triggered via the
/forgotendpoint. The email contains a link valid for one hour. - Email Change: When a user requests an email change, a confirmation link is sent to the new address, while a notification is sent to the old address.
- Community Notifications: Users receive alerts for new followers, comments, or likes if enabled in their settings.
- Administrative Alerts: The system emails
ABUSE_EMAILwhen a site is automatically flagged for phishing or when a user submits a manual report.
Sources: src/server.js:410-474, src/server.js:581-597, src/server.js:688-693, src/server.js:847-853
Verification Flow Diagram
This diagram illustrates the sequence of events during the account verification process.
Sources: src/server.js:410-438
Deliverability and Domain Configuration
Deliverability depends on proper DNS records at the domain registrar (e.g., Cloudflare). The project requires SPF, DKIM, and DMARC records to prevent emails from being flagged as spam.
Required DNS Records
- SPF (Sender Policy Framework): A TXT record authorizing the mail provider to send mail on behalf of the domain (e.g.,
v=spf1 include:resend.com ~all). - DKIM (DomainKeys Identified Mail): TXT or CNAME records provided by the SMTP host to sign outbound messages cryptographically.
- DMARC: A TXT record (
_dmarc) that tells receiving servers how to handle mail that fails SPF or DKIM checks. - Email Routing: Cloudflare Email Routing is utilized to forward
abuse@puppypad.orgto a monitored mailbox.
Sources: PLAN.md:2.7, README.md:Email that arrives
User Notification Settings
Members can control the frequency and types of emails they receive through the /notifications and /dashboard/guestbook views.
Configuration Options
| Feature | Email Options | Default |
|---|---|---|
| Guestbook | Instant, Daily Digest, or Off | daily |
| Social | Follows, Likes, Comments (Checkboxes) | User defined |
| Updates | Weekly digest of followed sites (Opt-in) | off |
Sources: src/views.js:296-302, src/views.js:605-610, src/server.js:936-946
Digest Processing
The application runs a periodic "housekeeping" task every hour. This task identifies users whose gb_digest_at or digest_at values are older than the required interval (24 hours for guestbooks, 7 days for site updates) and sends a consolidated email if new content exists.
Sources: src/server.js:936-963
Conclusion
The Email Routing & SMTP Configuration system is a vital infrastructure component of PuppyPad, ensuring secure account management and fostering community engagement through timely notifications. By abstracting delivery through nodemailer and providing comprehensive administrative and user-level controls, the system maintains high deliverability standards while allowing for flexible environment-based configurations.