Notification Service API

Outbound comms + CRM-lite. Delivery (SES + Twilio), contacts (leads + patients), campaigns (drips + scheduled + blasts), and preferences (HIPAA-aware). Replaces HubSpot entirely.

Overview

The Notification Service is a centralized API for all patient and internal notifications. Instead of each service integrating directly with SES, Twilio, HubSpot, and Slack, callers send a single POST /notify/send request and let the service handle template resolution, channel routing, delivery, and logging.

Base URL

https://api.yourera.com/notify

How It Works

1. Caller sends a POST /notify/send with a notification type and recipient data
2. Service resolves the template for that notification type
3. Template engine renders the template with provided variables
4. Channel config determines which channels are enabled for this type
5. Service dispatches to all enabled channels (email, SMS, HubSpot, Slack)
6. Each channel delivery is independent - one failure doesn't block others
7. All delivery attempts are logged with status, channel, and timestamps

Authentication

The /notify/send endpoint requires HMAC-SHA256 authentication. Admin endpoints (/notify/templates/*, /notify/channels/*) require an Admin JWT token.

HMAC Authentication (Send Endpoint)

Signature Formula

HMAC-SHA256(apiSecret, timestamp + '.' + JSON.stringify(body))

Node.js Example

import crypto from 'node:crypto';

const timestamp = new Date().toISOString();
const body = JSON.stringify({
  type: 'prescription_approved',
  recipient: { email: 'patient@example.com', phone: '5551234567' },
  variables: { patientName: 'Jane Doe', medication: 'Semaglutide' }
});

const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(timestamp + '.' + body)
  .digest('hex');

await fetch('https://api.yourera.com/notify/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: body,
});

Send Notification

Request Body

Example Request

{
  "type": "prescription_approved",
  "recipient": {
    "email": "jane@example.com",
    "phone": "5041234567",
    "name": "Jane Doe"
  },
  "variables": {
    "patientName": "Jane Doe",
    "medication": "Semaglutide 5mg/mL",
    "pharmacyName": "Galleria Medical Pharmacy"
  }
}

Success Response 200

{
  "success": true,
  "channels": [
    { "channel": "email", "status": "sent" },
    { "channel": "sms", "status": "sent" }
  ],
  "logId": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Notification Types

43 notification types organized in 3 categories. Each type is seeded on first deployment with an email template. SMS templates are added as A2P 10DLC registration completes.

General (29 types)

Orders (12 types)

Shipping (6 types)

Channel Matrix

The full channel matrix for all 43 notification types is managed through the Admin Portal. On initial deployment, all types are seeded with Email enabled and all other channels disabled. Channels can be toggled per-type via the admin UI or the PUT /notify/channels/:type API.

Available Channels

Template Engine

Templates use Mustache-style {{variableName}} placeholders. The template engine substitutes variables and handles edge cases gracefully:

• Missing variables render as empty string (no crash)
• undefined / null variables render as empty string
• Variables in email templates are HTML-escaped (XSS prevention)
• Variables in SMS templates are rendered raw (plain text)
• Empty template body causes that channel to be skipped

Example

// Template
"Hi {{patientName}}, your {{medication}} has been approved!"

// Variables
{ "patientName": "Jane", "medication": "Semaglutide" }

// Result
"Hi Jane, your Semaglutide has been approved!"

Templates CRUD

Admin endpoints for managing notification templates. Requires Admin JWT in Authorization: Bearer <token>.

Update Request Body

Channels CRUD

Admin endpoints for managing channel configuration per notification type.

Update Request Body

{
  "email": true,
  "sms": true,
  "hubspot": false,
  "slack": false
}

Delivery Log

Every notification dispatch is logged with:

Health Check

{
  "status": "ok",
  "service": "notification-service",
  "timestamp": "2026-03-20T12:00:00.000Z"
}

Admin Portal Integration

The admin portal at admin.yourera.com will include a Notifications page for managing the full notification lifecycle. The page provides:

• Type listing - all 43 types grouped by category (General, Orders, Shipping)
• Channel toggles - enable/disable email, SMS, push per type
• Template editor - edit email subject, HTML body, text body, SMS body for each type
• Delivery log viewer - search/filter notification delivery history
• Test send - send a test notification to verify templates

The admin portal calls the notification service Admin JWT-authenticated endpoints:

Email Templates & Design System

Overview

All patient-facing emails (except OTP login codes) use the YourEra branded design system. The design was originally created in HubSpot portal 244430850 and is now self-hosted. There are two categories of templates:

1. Image-based lifecycle emails - HubSpot-designed, full visual layouts using stacked images (welcome series, new patient, abandoned intake)
2. Branded transactional emails - HTML text content wrapped in the branded email shell with logo header + shared footer (prescription approved, shipment, dosing instructions, payment, provider message)

The OTP/login code email uses a minimal standalone layout with no heavy branding.

Image Hosting

All email images are self-hosted on CloudFront rather than the HubSpot CDN.

Assets include template images (JPG/GIF), the YourEra logo, and social media icons (Facebook, Instagram, LinkedIn).

Template Architecture

The template system is built around a shared branded wrapper that provides consistent header, footer, and styling across all transactional emails.

Helper functions available in templates.ts:

• ctaButton(text, href) - renders a styled call-to-action button
• infoBox(content) - renders a highlighted info box
• warningBox(content) - renders a warning-styled box

Available Templates

Branded Transactional Templates

OTP Template (Minimal Layout)

Image-Based Lifecycle Templates (HubSpot Workflows)

Sending Emails

Emails are sent via SendGrid using sendEmail() from src/lib/notifications/email.ts.

Sending Test Emails

Use the test script to send image-based HubSpot templates to a recipient for review:

# Test an image-based HubSpot template
SENDGRID_API_KEY=SG.xxx npx tsx scripts/send-test-email.ts <email> [template-name]

# Available template names:
#   abandoned-intake-1, abandoned-intake-2, new-patient-2,
#   new-patient-post-purchase, welcome-email-1, welcome-email-2,
#   welcome-email-3

DNS Requirements

The yourera.com domain must have proper email authentication records to ensure deliverability.

Shared Footer Content

All branded emails (those using brandedWrapper()) include the standard footer with:

• FDA compounding pharmacy disclaimer
• YourEra logo
• Privacy Policy + Contact us links
• Social media icons (Facebook, Instagram, LinkedIn)
• Company address: YourEra, 1331 Ochsner Blvd, Suite 200, Covington, LA 70433
• Copyright notice

Roadmap

Phase 1 - Email Only (Current)

• 43 notification types seeded with email templates
• Email delivery via AWS SES (noreply@yourera.com)
• Admin portal can toggle types on/off and edit templates
• SMS channel disabled (pending Twilio A2P 10DLC registration)

Phase 2 - SMS

• Complete Twilio A2P 10DLC registration
• Enable SMS templates for patient-facing notifications
• Admin portal gains SMS template editing

Phase 3 - Intake Magic Link + Abandoned Checkout

• magic_link and abandoned_checkout types go live
• Intake gateway tracks session start timestamps
• 30-minute inactivity trigger sends abandoned_checkout email
• Magic link includes signed token for intake resume

Phase 4 - Scheduled Notifications

• Follow-up reminders (due, past due, 2 days)
• Check-in reminders (3-month, 4-month)
• Subscription renewal notices
• Delivery estimates (tomorrow, out for delivery)
• Requires a notification scheduler (cron or EventBridge)

Phase 5 - Push Notifications

• Mobile push via APNs/FCM
• In-app notification center
• Admin portal gains push template editing

What's Missing (Dependency Tracker)