Why Your Form Auto-Reply Email Did Not Arrive

ED'; const job = await createDeliveryJob({ idempotencyKey: ${submission.id}-${matchedRule.id}, recipient: targetAddress, template: matchedRule.templateId, variables: submission.payload });

if (!job) { audit.status = 'FAIL'; audit.metadata.errorDetail = 'Failed to create delivery job'; return audit; } audit.metadata.jobId = job.id;

// Stage 4: Provider Handoff audit.pipelineStage = 'PROVIDER_HANDOFF'; const providerResult = await dispatchToProvider(job);

if (providerResult.status === 'REJECTED') { audit.status = 'FAIL'; audit.metadata.errorDetail = providerResult.reason; return audit; }

audit.metadata.providerMsgId = providerResult.messageId; audit.metadata.providerStatus = 'ACCEPTED';

return audit; }

// Helper to extract recipient based on dynamic mapping function extractRecipient(submission: FormSubmission, mapping: Record<string, string>): string | null { const fieldKey = mapping[submission.formId]; const value = submission.payload[fieldKey]; return typeof value === 'string' ? value.trim() : null; }

**Rationale:**
*   **Granular Stages:** By separating `VALIDATION` from `RULE_EVAL`, you can distinguish between a missing email field and a conditional skip.
*   **Metadata Enrichment:** Storing `providerMsgId` allows correlation with provider dashboards. If the provider reports a bounce, you can trace it back to the specific submission.
*   **Early Returns:** The function exits immediately on failure, preventing unnecessary processing and ensuring the audit trail reflects the exact point of failure.
*   **Idempotency:** The job creation includes an idempotency key derived from the submission and rule IDs, preventing duplicate sends during retries.

### Pitfall Guide

| Pitfall | Explanation | Fix |
| :--- | :--- | :--- |
| **The "Enabled" Fallacy** | Assuming the auto-reply toggle guarantees execution. The toggle only enables the pipeline; it does not validate data or rules. | Implement pipeline logging. Verify that the rule evaluation stage returns a match for the specific submission. |
| **Field Mapping Drift** | Form schema changes (e.g., renaming `email` to `work_email`) break recipient resolution without alerting the operator. | Use explicit field mapping configurations. Add schema validation checks that verify required fields exist before processing. |
| **Accepted vs. Delivered** | Treating provider "accepted" status as final delivery. Providers may accept the message but later bounce or suppress it. | Configure webhook listeners for async events. Monitor `BOUNCED`, `SUPPRESSED`, and `COMPLAINT` states separately from `ACCEPTED`. |
| **The No-Reply Trap** | Email copy instructs users to "reply," but the `Reply-To` header points to an unmonitored address or is missing. | Align email copy with configuration. If using `no-reply@`, ensure the body provides an alternative support channel. Audit `Reply-To` headers regularly. |
| **Auth Neglect** | Sending from a custom domain without SPF, DKIM, or DMARC records. This increases suspicion and spam placement. | Verify DNS records before launch. Use provider tools to check domain health. Ensure DMARC policy is configured to monitor or quarantine. |
| **Test Data Blindness** | Testing with synthetic addresses that may be suppressed or routed to junk by default. | Use real inboxes for QA. Test across multiple providers (Gmail, Outlook, corporate gateways) to verify inbox placement. |
| **Template Variable Errors** | Missing variables in the template cause rendering failures or empty emails, which providers may flag as low quality. | Validate template variables against the submission payload. Implement fallback values for optional fields. |

### Production Bundle

#### Action Checklist

- [ ] **Audit Field Mappings:** Verify that recipient field mappings align with the current form schema. Check for renamed or removed fields.
- [ ] **Implement Pipeline Logging:** Deploy the state-trace architecture to capture audit trails at each stage of the auto-reply workflow.
- [ ] **Configure Provider Webhooks:** Set up endpoints to receive async events (bounces, complaints, suppressions) from the email provider.
- [ ] **Review Dispatch Rules:** Ensure conditional logic matches business requirements. Test edge cases where rules might skip expected submissions.
- [ ] **Validate Domain Authentication:** Confirm SPF, DKIM, and DMARC records are correctly configured for the sending domain.
- [ ] **Test Inbox Placement:** Send test submissions to real inboxes across different providers. Check spam folders, tabs, and corporate gateways.
- [ ] **Audit Email Copy:** Verify that `Reply-To` headers match the instructions in the email body. Ensure no dead ends exist.
- [ ] **Monitor Reputation:** Track provider metrics like bounce rates and complaint rates. Investigate anomalies immediately.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Low Volume Forms** | Direct API dispatch with synchronous logging | Simplicity reduces overhead. Sufficient for <100 submissions/day. | Low (Minimal infrastructure) |
| **High Volume Forms** | Queue-based dispatch with async processing | Decouples form submission from email sending. Improves reliability and scalability. | Medium (Queue infrastructure) |
| **Complex Conditional Logic** | Rule engine with explicit audit trails | Enables granular debugging of why specific submissions were skipped or routed. | Low (Development effort) |
| **Strict Compliance Requirements** | Provider with detailed reporting and suppression management | Ensures auditability and adherence to regulations like GDPR or CAN-SPAM. | High (Premium provider features) |

#### Configuration Template

Use this template to define auto-reply configurations with validation and rule enforcement.

```json
{
  "autoReplyConfig": {
    "formId": "form_12345",
    "enabled": true,
    "recipientFieldMapping": {
      "default": "email_address"
    },
    "rules": [
      {
        "name": "Standard Confirmation",
        "conditions": [
          { "field": "inquiry_type", "operator": "equals", "value": "general" }
        ],
        "templateId": "tmpl_standard_confirm",
        "replyTo": "support@company.com"
      },
      {
        "name": "Booking Confirmation",
        "conditions": [
          { "field": "inquiry_type", "operator": "equals", "value": "booking" },
          { "field": "booking_status", "operator": "equals", "value": "confirmed" }
        ],
        "templateId": "tmpl_booking_confirm",
        "replyTo": "bookings@company.com"
      }
    ],
    "validation": {
      "requireEmail": true,
      "emailRegex": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"
    }
  }
}

Quick Start Guide

1. Define Schema: Create the SubmissionAuditTrail interface and integrate it into your form processing pipeline.
2. Add Logging Middleware: Wrap your auto-reply logic with the traceAutoReply function to capture state transitions.
3. Set Up Webhooks: Configure your email provider to send delivery events to your application. Store these events linked to the providerMsgId.
4. Run Synthetic Tests: Submit test forms with various payloads. Verify that audit logs reflect the expected states and that emails arrive in target inboxes.
5. Monitor Dashboard: Build a simple view to display recent audit trails. Filter by status: FAIL to quickly identify and resolve issues.

By treating form auto-replies as a state machine, you gain visibility into every step of the delivery process. This approach eliminates guesswork, reduces debugging time, and ensures that confirmation emails reach respondents reliably.