Transactional Emails (Zeptomail)

Relevant source files

The following files were used as context for generating this wiki page:

• pages/api/dispatch.ts
• public/mails/email.html
• README.md
• package.json
• tests/api/dispatch.spec.ts
• pages/index.tsx
• components/success.tsx

The transactional email system is a core feature of the Heyme application, responsible for delivering scheduled video messages to users. It leverages the Zeptomail service to send emails containing links to these messages. The primary function is to check for videos scheduled for the current day, construct a personalized email for each, send it, and mark the video as sent to prevent duplicate notifications.

This system is orchestrated by a single API endpoint, /api/dispatch, which connects to the MySQL database, processes the video queue, and interacts with the Zeptomail API. The email content is dynamically generated from an HTML template.

Sources: README.md:40, pages/api/dispatch.ts

Architecture and Data Flow

The email dispatch process is initiated by a call to the /api/dispatch endpoint. This endpoint acts as a daily cron job handler, fetching and processing all video messages scheduled for delivery on that day.

The overall flow is as follows:

1. An external trigger (e.g., a cron job) invokes the /api/dispatch endpoint.
2. The handler connects to the MySQL database.
3. It queries the Videos table for all records where the send_at date matches the current date and the sent flag is not 1.
4. For each video found, it constructs a personalized email.
5. It uses the Zeptomail client to send the email to the recipient's address.
6. Upon successful sending, it updates the video's record in the database, setting the sent flag to 1.
7. After processing all videos, the database connection is closed.

Sources: pages/api/dispatch.ts:38-100, README.md:40

This diagram illustrates the high-level data flow for the email dispatch process.

API Endpoint: POST /api/dispatch

This is the central API endpoint that manages the email dispatch logic.

Sources: pages/api/dispatch.ts:38-103

Sequence of Operations

The following diagram details the sequence of interactions between the API handler, the database, and the Zeptomail service.

Key Functions

The dispatch.ts file contains several key helper functions.

Function	Description	Source File
fetchAllVideosForToday	Queries the Videos table for all entries where send_at matches the current date.	pages/api/dispatch.ts:27-31
updateVideoToSent	Updates a video record in the database by its ID, setting the sent column to 1.	pages/api/dispatch.ts:33-37
getEmailContent	Reads an HTML template from the filesystem and replaces placeholders with dynamic data.	pages/api/dispatch.ts:11-20
handleDispatchEmails	The main API handler function that orchestrates the entire process of fetching, sending, and updating.	pages/api/dispatch.ts:39-101

Email Content Generation

Emails are generated from a static HTML template which is populated with dynamic data for each recipient.

Sources: pages/api/dispatch.ts:11-20, public/mails/email.html

HTML Template

The base template is located at public/mails/email.html. It's a standard HTML email structure with specific placeholders that are replaced by the getEmailContent function.

Sources: public/mails/email.html, pages/api/dispatch.ts:12-13

Template Placeholders

The getEmailContent function performs a string replacement for the following placeholders within the HTML template.

Placeholder	Replacement Value
{{REPLACE_WATCH_LINK_HERE}}	The full URL to watch the video message, constructed from process.env.SITE_URL and the video ID. Example: https://heyme.io/watch/123.
{{REPLACE_GREETING_HERE}}	A personalized greeting. It differs based on whether the user sent the message to themselves or to someone else.
{{REPLACE_BODY_HERE}}	A static body text explaining that the message was sent via the Heyme service.
{{REPLACE_OUTRO_HERE}}	A static closing message.

Sources: pages/api/dispatch.ts:15-18, public/mails/email.html:301, 357, 393, 402, tests/api/dispatch.spec.ts:6-25

Configuration and Dependencies

The system relies on specific npm packages and environment variables to function correctly.

Dependencies

The following packages listed in package.json are essential for the email dispatch functionality.

Package	Usage
zeptomail	The official client library for the Zeptomail API.
knex	SQL query builder for interacting with the database.
mysql	The database driver for MySQL.
dayjs	A utility library for date and time manipulation.

Sources: package.json:48, 51, 52, 60

Environment Variables

The service requires the following environment variables to be set.

Variable	Description	Source File
ZEPTOMAIL_TOKEN	The API token for authenticating with Zeptomail.	pages/api/dispatch.ts:51
SITE_URL	The base URL of the application, used for links.	pages/api/dispatch.ts:84

Sources: pages/api/dispatch.ts:51, 84

Summary

The transactional email system, powered by Zeptomail, is a critical backend process in the Heyme application. It reliably delivers scheduled messages, which is the core promise of the product to its users. The logic is encapsulated within the /api/dispatch endpoint, which ensures that videos are fetched, emails are personalized and sent, and records are updated to prevent resending. The modular design, with separate functions for data access, content generation, and email sending, makes the system maintainable and testable.

Sources: README.md:4-6, pages/api/dispatch.ts, pages/index.tsx:40-42