name: contact-form-builder-ses
description: Build AWS SES email features with reCAPTCHA v3, Zod validation, XSS sanitisation, and rate limiting. Uses placeholders until env vars added to Vercel. Dual emails (owner + customer confirmation). Triggers: contact form, email form, enquiry form, ses email, newsletter signup, booking form, callback request.
updated: 2025-01-18

AWS SES Contact Form Builder

Purpose: Contact forms and email features using AWS SES. Works with placeholders during development - add env vars to Vercel when ready to go live.

When to Use

• "create a contact form"
• "add email functionality"
• "build enquiry form"
• "newsletter signup"
• "callback request form"
• "booking request with email"
• Any feature sending email from website

Architecture Overview

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  React Form     │────▶│  API Route      │────▶│  AWS SES        │
│  + reCAPTCHA v3 │     │  + Validation   │     │  (eu-west-1)    │
└─────────────────┘     │  + Sanitisation │     └────────┬────────┘
                        │  + Rate Limit   │              │
                        └─────────────────┘              ▼
                                                 ┌──────────────┐
                                                 │ DUAL EMAILS  │
                                                 │ 1. Owner     │
                                                 │ 2. Customer  │
                                                 └──────────────┘

Placeholder Reference

Use these placeholders throughout - Claude MUST ask user to provide values:

What to Ask User

MANDATORY before building:

1. Company Details
2. Company name
3. Phone number
4. Address
5. Company number (if displaying)

6. Website URL

7. Email Configuration

8. Owner notification email (where enquiries go)
9. From email (must be SES verified)

10. From display name

11. Brand Colours

12. Primary colour (headers, backgrounds)
13. Secondary colour (accents, highlights)

14. Accent colour (CTAs, links)

15. Form Fields Needed

16. Which fields? (name, email, phone, subject, message, etc.)
17. Which are required?

18. Any special validation? (min length, formats)

19. Personality/Tone

20. Formal, friendly, or witty?
21. This affects email greetings and copy

Technology Stack (Non-Negotiable)

Critical Implementation Rules

1. reCAPTCHA v3 Loading (MUST USE)

// ✅ CORRECT - loads before form submit
<Script
  src={`https://www.google.com/recaptcha/api.js?render=${siteKey}`}
  strategy="afterInteractive"
/>

// ❌ WRONG - causes timeout errors
strategy="lazyOnload"  // NEVER use this

2. Dual Email (ALWAYS SEND BOTH)

Every form submission MUST send TWO emails:
1. Owner notification - Full details with reply-to set to customer
2. Customer confirmation - Thank you with summary of their message

Never send just one. This is enterprise standard.

3. Email Template Rules

<!-- ✅ CORRECT - table layout for Outlook -->
<table style="background-color: {{PRIMARY_COLOR}};">

<!-- ❌ WRONG - breaks in Outlook -->
<div style="display: flex;">

• Use TABLE layouts (not flexbox/grid)
• Inline ALL CSS (no external stylesheets)
• Add solid colour BEFORE gradients (fallback)
• Test in Gmail, Outlook, Apple Mail

4. Validation Chain

User Input → Zod Schema → DOMPurify Sanitise → Safe Data → Send Email

Never skip any step. See SECURITY.md for full implementation.

5. Rate Limiting

// Default: 5 requests per hour per IP
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(5, '1 h'),
})

File Structure to Create

src/
├── app/
│   ├── contact/
│   │   ├── page.tsx              # Contact page with form
│   │   └── metadata.ts           # SEO metadata
│   └── api/
│       └── contact/
│           └── route.ts          # API handler
├── components/
│   └── ContactForm.tsx           # Reusable form component
└── lib/
    ├── validation.ts             # Zod schemas
    ├── sanitize.ts               # DOMPurify helpers
    ├── ratelimit.ts              # Rate limiting setup
    └── env.ts                    # Environment validation

Environment Variables

# AWS SES (REQUIRED)
AWS_REGION=eu-west-1
AWS_ACCESS_KEY_ID={{ASK_USER}}
AWS_SECRET_ACCESS_KEY={{ASK_USER}}

# Email addresses (REQUIRED)
EMAIL_FROM={{FROM_EMAIL}}
EMAIL_FROM_NAME={{FROM_NAME}}
EMAIL_TO={{OWNER_EMAIL}}

# reCAPTCHA v3 (REQUIRED)
NEXT_PUBLIC_RECAPTCHA_SITE_KEY={{ASK_USER}}
RECAPTCHA_SECRET_KEY={{ASK_USER}}

# Rate limiting (REQUIRED for production)
UPSTASH_REDIS_REST_URL={{ASK_USER}}
UPSTASH_REDIS_REST_TOKEN={{ASK_USER}}

Testing Checklist

• [ ] Submit with valid data → success
• [ ] Submit with missing required fields → validation error
• [ ] Submit with XSS payload <script>alert('xss')</script> → sanitised
• [ ] Submit 6 times quickly → rate limited on 6th
• [ ] Check owner receives notification email
• [ ] Check customer receives confirmation email
• [ ] Test reply-to works (reply goes to customer)
• [ ] Test emails render correctly in Gmail
• [ ] Test emails render correctly in Outlook
• [ ] Test mobile responsiveness of form

Common Failures & Fixes

Additional Resources

• IMPLEMENTATION.md - Full code templates with placeholders
• SECURITY.md - Validation, sanitisation, rate limiting code
• scripts/ - Copyable code files

UK Standards (Always Apply)

• UK English spelling (colour, enquiry, organisation)
• eu-west-1 region for GDPR compliance
• British date format (DD/MM/YYYY)
• British phone format (+44)
• Professional business tone