Welcome Email Plan (Brevo API)

Welcome Email Plan (Brevo API)

1) Current Status (Confirmed)

Brevo API is now implemented for uninstall flow:

• app/lib/email.server.js uses Brevo transactional API env vars.
• sendGoodbyeEmail() is implemented and production-safe (returns { ok, error }).
• sendLowBalanceAlert() is currently a stub (console only).

Decision update: welcome and uninstall email flows are both on Brevo API.

Implementation status update:

• Done: sendWelcomeEmail() is implemented and called from afterAuth with idempotency (welcome_email_sent).
• Done: sendGoodbyeEmail() is implemented and wired to uninstall webhook updates.
• Done: .env / .env.sample use Brevo variables (BREVO_*) only.
• Pending per environment: run npx prisma migrate deploy to ensure shops email flag columns exist everywhere.

---

2) Goal

Send a welcome email to merchants when they install/sign up successfully, with:

• modern visual style
• strong readability
• good font stack (email-safe first, web font optional)
• clear CTA to open app settings
• optional onboarding checklist

---

3) Trigger Strategy

Recommended trigger point: afterAuth in app/shopify.server.js.

Why:

• runs on successful OAuth
• has merchant identity context (shopDomain, shopName, shopEmail)
• closest point to “signup/install success”

Important: prevent duplicate sends.

Idempotency approach (Shop fields only)

Do not create a new table. Use boolean flags on Shop:

• welcome_email_sent (default false)
• uninstall_email_sent (default false)

Optional companion fields for debugging/retry visibility:

• welcome_email_sent_at (nullable DateTime)
• welcome_email_error (nullable text)
• uninstall_email_sent_at (nullable DateTime)
• uninstall_email_error (nullable text)

Minimum requirement from this plan:

• Use booleans as source of truth (true = already sent; skip duplicate send).

---

4) Env and Config

Add Brevo env vars:

• BREVO_API_KEY (secret; keep only in .env, never commit real value in docs/repo)
• BREVO_FROM_EMAIL
• BREVO_FROM_NAME

Optional:

• BREVO_REPLY_TO_EMAIL

• BREVO_REPLY_TO_NAME

• WELCOME_EMAIL_ENABLED=true (feature flag)

• WELCOME_EMAIL_REPLY_TO=support@appifire.com

---

5) Template Spec (Modern Style)

Use multipart email:

• plain text fallback
• HTML template

Typography

Primary stack (safe):

'Inter', 'Segoe UI', Roboto, Helvetica, Arial, sans-serif

Notes:

• Many clients ignore custom web fonts; keep robust fallback stack.
• Design for email client constraints (inline styles, table-based layout where needed).

Visual style

• Background: very light gray #F6F8FB
• Card container: white, rounded corners
• Accent brand color: use app primary (e.g. #5C6AC4)
• Headline: bold, friendly
• Body copy: 15-16px equivalent, high contrast
• CTA button: solid brand color, large touch target

Suggested sections

1. Greeting (Hi {shopName})
2. One-line value proposition
3. Quick start checklist (3 bullets)
4. CTA: “Open App Settings”
5. Support line + reply-to
6. Footer (you received this because…)

---

6) Example Email Content

Subject

Welcome to AppiFire AI Chat - Let's get your store live

Preview text

You're set up. Add your first settings in under 2 minutes.

Body copy

• “Thanks for installing AppiFire AI Chat.”
• “Your storefront assistant is ready - now let’s personalize it.”
• Checklist:
  • Set welcome message
  • Choose widget style/colors
  • Test first customer question

CTA link target:

${SHOPIFY_APP_URL}/app/settings (or your real settings route)

---

7) Implementation Tasks

1. Add sendWelcomeEmail() to app/lib/email.server.js (or app/lib/brevo.server.js)
2. Implement Brevo API client call (POST https://api.brevo.com/v3/smtp/email)
3. Add HTML builder + plain text builder
4. Add idempotency fields on Shop (no new table):
   • welcome_email_sent
   • uninstall_email_sent
5. In afterAuth, send only if:
   • email exists
   • feature flag enabled (if used)
   • welcome_email_sent !== true
6. Persist send success/failure state on Shop:
   • success: set welcome_email_sent = true
   • failure: keep false and store error message (optional)
7. Log with shop domain + reason on failure

---

8) Failure Handling

• Never fail OAuth/install because email fails.
• Send email async or fire-and-forget after core install path.
• Capture errors for later retry:
  • “Brevo API key not configured”
  • 401/403 from Brevo API
  • 429 rate limit
  • timeout/network

---

9) QA Checklist

• New install with valid shop email -> welcome email arrives
• Re-auth/login of same merchant -> no duplicate welcome email
• Missing email -> no send, graceful log
• Brevo key missing/invalid -> no crash, error captured
• Email renders correctly on:
  • Gmail web/mobile
  • Outlook web
  • Apple Mail

---

10) Rollout

1. Enable in staging/test store first
2. Verify template rendering and CTA route
3. Enable in production
4. Monitor:
   • send success rate
   • bounces/complaints
   • open/click (if tracking added later)