Email Service & Templates

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/email-service-templates/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A free core feature that provides reliable email delivery infrastructure and a library of hand-modelled transactional email templates (order confirmation, shipment tracking, password reset, review requests) that merchants can customize and send to customers.

The problem

Merchants need reliable email delivery for order confirmations, shipment notifications, and password resets. Building email templates from scratch takes time and skill. Email delivery is unreliable if sender domain is not configured properly.

What it does

• Transactional email templates: order confirmation, shipment tracking, delivery confirmation, return authorization, password reset, account verification, review request, refund confirmation
• Email template editor (WYSIWYG or HTML code editor)
• Template customization (merchant’s logo, colors, sender name/email, footer legal text)
• Email variable replacement ({{order.id}}, {{customer.name}}, {{product.name}}, {{shipment.trackingUrl}})
• Scheduled email sends (send order confirmation 1 minute after order, shipment notification after shipment is marked shipped)
• Bulk resend (merchant can manually resend order confirmation if customer claims they didn’t receive it)
• Email preview and test send (render preview, send test email to merchant’s email address)
• Spam testing (run preview through SpamAssassin to ensure emails reach inbox)
• Email authentication help (guide merchant through SPF, DKIM, DMARC setup for their domain)
• SMTP provider configuration (support Sendgrid, Mailgun, AWS SES; merchant chooses which to use)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• SMTP relay (customer brings their own SendGrid account; we relay through their account) — that’s email-campaign-builder or custom-smtp paid module
• Marketing email templates (promotional, newsletter) — those are in email-newsletter-campaigns or email-campaign-builder
• Email automation (if customer signs up, send welcome email) — paid ‘email-automation’ module owns triggers and sequences
• Advanced personalization (dynamic content blocks, if-then rules) — paid ‘personalized-email-campaigns’ owns this
• SMS or push notifications (email only) — separate paid modules
• Email frequency capping (don’t send more than 1 email per day per customer) — paid ‘email-frequency’ owns this
• Predictive send time (optimize delivery time per customer) — paid ‘send-time-optimization’ owns ML

Data model

New entities: email.templates {id, name, type (order-confirmation/shipment/password-reset/etc), subject, html, variables[], senderName, senderEmail, replyToEmail, logoUrl, footerText, isCustomized, createdAt}; email.sends {id, templateId, toEmail, toName, substitutionData (json), scheduledFor, sentAt, deliveredAt, bounceType (none/soft/hard), complained (bool), unsubscribed (bool), createdAt}; email.deliveryStatus {id, sendId, status (queued/sent/delivered/bounced/complained), eventAt, message}; email.logs {id, sendId, toEmail, subject, sentAt, deliveryStatus, messageId}; smtp.config {id, merchantId, provider (sendgrid/mailgun/aws-ses/smtp), apiKey (encrypted), fromEmail, replyToEmail, isActive}.

API

• GET /api/email/templates
• GET /api/email/templates/{id}
• PATCH /api/email/templates/{id}
• POST /api/email/send
• POST /api/email/send/{id}/resend
• GET /api/email/sends
• GET /api/email/sends/{id}
• POST /api/email/preview
• POST /api/email/test-send
• POST /api/email/spam-test
• POST /api/smtp/config
• GET /api/smtp/config
• POST /api/smtp/test-connection
• GET /api/email/logs

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Email templates library: show built-in templates, edit each one. Template editor: WYSIWYG or HTML code editor, live preview, show available variables. Template customization: upload logo, change colors, edit sender name/email, add footer legal text. Test send and preview: render preview in browser, send test email to merchant. Spam testing: run template through SpamAssassin, show spam score and recommendations. SMTP provider setup: guide merchant through SendGrid/Mailgun/AWS SES setup, paste API key, test connection. Email delivery logs: view all transactional emails sent, delivery status, timestamp, bounce reason. Bulk resend: select date range and recipient, resend emails. Unsubscribe management: view unsubscribe list, show reasons. Email authentication help: provide step-by-step guide for SPF, DKIM, DMARC setup.

The seam — why this is core

Core owns the interface (template editor, variable replacement, send control) and honest email infrastructure: transactional email templates (order confirmation, shipment, password reset — these are essential, infrastructure-level), email variable replacement and preview (basic personalization), SMTP provider configuration (SendGrid, Mailgun, AWS SES — core supports multiple providers), email delivery status tracking (infrastructure concern). Paid modules own marketing email templates (promotional, newsletter), email automation (scheduled sends, triggered sends), advanced personalization (dynamic content, if-then rules).

Core owns the interface + honest email infrastructure; transactional mail is infrastructure, not a per-country obligation or credential.

Dependencies

• Orders module (to populate {{order.*}} variables)
• Customers module (to populate {{customer.*}} variables)
• Products module (to populate {{product.*}} variables)
• Shipments module or similar (to populate {{shipment.trackingUrl}})
• SMTP provider (SendGrid, Mailgun, AWS SES)
• Scheduler (to schedule email sends)
• Audit log (to log email send events)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A built-in ‘Order Confirmation’ template renders with {{order.id}}, {{customer.firstName}}, {{product.name}}, {{order.total}} replaced with actual order data
• Email preview shows template in desktop (1200px) and mobile (375px) viewports; no text overflow or broken layout
• Spam test runs template through SpamAssassin; if spam score > 5, show warnings
• A test send to merchant@example.com arrives within 5 seconds
• An order confirmation email sent to customer@example.com shows ‘sent’ status immediately; status changes to ‘delivered’ within 30 minutes
• A soft bounce (mailbox full) triggers automatic retry; email is resent after 1 hour, then 4 hours, then 24 hours
• A hard bounce (invalid email) marks send as ‘bounced - hard’ and prevents future sends to that email
• SMTP provider test fails with clear error message if API key is invalid or credentials are incomplete
• Unsubscribe link in template is rendered as ‘{{unsubscribeLink}}’ and replaced with actual unsubscribe URL in sent email
• Email log shows all transactional emails sent in last 30 days, filterable by template type, recipient, status, date range

Risks

Email rendering: if HTML template has nested tables or complex CSS, it may render incorrectly in Outlook or Gmail; test against major clients. Spam delivery: if domain is not authenticated (SPF/DKIM/DMARC), emails land in spam; educate merchant in UI. SMTP credential exposure: if API key is logged in plaintext or exposed in error messages, security is compromised; encrypt at rest. Variable injection: if template contains user-supplied HTML with {{variable}} tokens, XSS is possible; sanitize on save, render in iframe. Email log size: if logging all sends, database grows rapidly (millions/month); implement log rotation and archiving. Bounce handling complexity: if ISPs report bounces asynchronously or inconsistently, bounce detection is unreliable; log all events and provide manual bounce list upload. Sender reputation: if merchant sends high volume without proper authentication, domain reputation drops; educate on SPF/DKIM/DMARC. Rate limiting: if SMTP provider rate-limits, email sending may slow down; implement queue and backoff.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.