32 — Email/SMS Operational Detail (Blueprint §4)

32 — Email/SMS Operational Detail (Blueprint §4)

Source: 02-Implementation-Blueprint.md — §4) Email/SMS Workflow (Operational Detail).

Note: 07-email-sms-request-delivery-pipeline.md focuses on implementation architecture.
This file is the operational behavior contract for runtime execution and support.

This document is a build spec only. No code changes are implied until a task references this file.

---

0) Goal (one sentence)

Define exact operational behavior for request messaging so every request moves through a predictable lifecycle from schedule to send to reminders to completion.

---

1) Canonical lifecycle (from blueprint)

1. Order event webhook received.
2. Eligibility evaluated against campaign rules.
3. Split eligible delivered order items into product-level request jobs.
4. Create one request row per delivered product with token and scheduled send time.
5. Worker/cron sends one message per request row.
6. Track delivery/open/click events.
7. If no submission by reminder window, send reminder.
8. Stop reminders when submission is completed.

Treat these 8 steps as the source of truth for runtime operations.

---

2) Operational states and timing

2.1 Request state lifecycle

Recommended status path:

• scheduled
• queued
• sent
• clicked
• submitted
• terminal alternatives: failed, expired

2.2 Timing controls

• Initial send time = trigger event time + campaign delayDays
• Reminder send time = first sentAt + reminderDelayDays (+ repeated windows up to maxReminders)
• All scheduling in UTC

---

3) Message dispatch contract

Each TestimonialRequest should attempt to send exactly once per planned send slot.

3.1 Required inputs per send attempt

• destination channel (email/sms/both)
• rendered template content
• submission link token URL
• campaign and request IDs for traceability

3.2 Required outputs

• status update on request row
• event row in TestimonialRequestEvent
• provider reference (if available)

---

4) Event taxonomy and semantics

For operational consistency, map events:

• queued — request ready for worker processing
• sent — provider accepted send request
• delivered — provider delivery confirmation (if available)
• opened — open tracking fired (email only; optional)
• clicked — customer opened submission link
• failed — send attempt failed

If provider lacks delivered/open support, keep those events optional and document as such in logs and UI.

---

5) Reminder policy contract

Reminder is allowed only when all are true:

1. campaign reminderEnabled=true
2. reminderCount < maxReminders
3. request not submitted
4. required reminder window elapsed

5.1 Stop conditions (hard)

Stop future reminders when:

• request status is submitted
• request status is expired
• campaign is paused/archived before reminder execution

---

6) Failure handling operations

6.1 Send failure

• set request lastError
• write failed event
• retry by policy (bounded attempts)

6.2 Retry policy (recommended)

• exponential backoff with max attempts (e.g. 3)
• after max attempts, mark terminal failed

6.3 Dead-letter visibility

Failed rows must be visible in Requests Log screen with clear reason.

---

7) Idempotency and replay behavior

7.1 Webhook replay

• duplicate webhook deliveries must not create duplicate request rows

7.2 Worker replay

• re-running send worker must not re-send already-sent slots unless explicit resend action exists

7.3 Event replay safety

• avoid duplicate event records with identical (requestId, eventType, providerMessageId, eventAt-window) where practical

---

8) Operational monitoring expectations

Track at minimum:

• requests scheduled per day
• send success rate
• failure rate by provider/channel
• click-through rate
• reminder send volume

Use these for on-call/support diagnostics and merchant-facing status confidence.

---

9) Runbook actions (support/ops)

When issues occur:

1. Check request row status and lastError
2. Inspect event stream for missing sent or clicked
3. Confirm campaign status and reminder settings
4. Verify provider credentials and quotas
5. Retry failed sends if still actionable and not submitted

---

10) SLA-style expectations (internal)

• request creation from webhook: near-real-time (seconds)
• due-send worker latency: within scheduler interval (e.g. <= 5 minutes)
• event persistence: same transaction/window as send acknowledgement

If SLOs breach, raise operational alert.

---

11) Acceptance checklist

• All 8 blueprint workflow steps are represented in code paths and logs.
• Reminder stop conditions work correctly.
• Failed sends are visible and diagnosable.
• Duplicate webhook replay is safe.
• Channel support differences (email vs sms) are documented and handled gracefully.

---

12) Suggested implementation linkage

Use this doc as operational reference while implementing:

• 07-email-sms-request-delivery-pipeline.md (system design)
• 13-requests-log-blueprint-screen-10.md (visibility UI)
• 16-templates-screen-4.md (template rendering)
• 22-integration-and-processing-plan-blueprint-section-7.md (cross-module flow)

---

13) References

• 02-Implementation-Blueprint.md — Section 4
• 01-Post-Purchase-Video-Testimonial-Collector-Plan.md — messaging + reminder scope

---

14) Note on numbering

This folder already includes 05 through 31 plans. This file is 32-....