✅ Phase 11.6: Email Service Integration (Production-Ready)

[vimal-java-dev]

11.6: Goal

• Send email notification when the contact form is submitted
• Use Spring Boot Mail (SMTP)
• Secure credentials using .env (Docker + VPS)
• Production-ready setup (no hardcoding secrets)

---

This is exactly the right stage to introduce email as a side-effect service in our backend. Since our stack is already production-oriented (Docker, CI/CD, Redis, PostgreSQL), we’ll implement this cleanly with separation of concerns, async handling, and secure config.

We’ll implement this in 7 structured steps:

1️⃣ Choose SMTP Provider (Critical Decision)

Use a reliable SMTP provider—do NOT use raw Gmail in production unless it's temporary.

Recommended:

• SendGrid (best balance)
• Mailgun
• Amazon SES (best for scale)

👉 For now, I’ll assume Gmail SMTP (quick start), but the structure will be provider-agnostic.

2️⃣ Add Dependency

pom.xml

3️⃣ Environment Variables (SECURE)

On VPS → .env

⚠️ Use App Password, NOT your Gmail password.

Docker Compose (important)

services:
  contact-api:
    env_file:
      - .env

4️⃣ Spring Boot Config (NO HARDCODING)

application-prod.yml

5️⃣ Create Email Service Layer

📁 Structure

service/
  EmailService.java
  impl/
    EmailServiceImpl.java

6️⃣ Integrate with Contact Flow

• 👉 DO NOT send email directly in controller
• 👉 Use service layer after DB save

7️⃣ Make It Production-Grade (IMPORTANT)

✅ A. Async Email (Non-blocking API)

Add:
Main class

Update Email Service
👉 Prevents API delay if SMTP is slow

✅ B. Add Logging + Failure Handling

✅ C. Optional (Advanced - Recommended Later)

• Retry using Spring Retry
• Queue-based system (Redis / Kafka)
• HTML emails (Thymeleaf templates)

🔥 Architecture After This

Controller
   ↓
ContactService
   ↓
PostgreSQL (save)
   ↓
EmailService (async)
   ↓
SMTP Provider

🚀 Deployment Checklist

• .env added on VPS
• Docker container restarted
• SMTP credentials verified
• Port 587 allowed (some VPS block it ⚠️)
• Test via API (Postman/frontend)

[vimal-tech-dev]

Assign me:

Would be part of the last service.

[vimal-tech-dev]

✅ Instead of using Gmail SMTP

✅ Updated Decision (Better Architecture)

👉 Used Zoho SMTP directly

Why this is the correct move:

• ✅ Matches our domain (vimaltech.dev)
• ✅ Better deliverability (SPF/DKIM already aligned)
• ✅ No Gmail restrictions
• ✅ More production-like setup

🔧 Zoho SMTP Configuration

Use this instead:

MAIL_HOST=smtp.zoho.com
MAIL_PORT=587
MAIL_USERNAME=vimal.patel@vimaltech.dev
MAIL_PASSWORD=your-zoho-password-or-app-password
MAIL_FROM=vimal.patel@vimaltech.dev

---

🚀 STEP 1️⃣ — Choose SMTP Provider (Decision First)

⚠️ Important (Do THIS carefully)

1️⃣ Enable App Password (Recommended)

2️⃣ SMTP Settings (Confirmed)

We are now doing:
Frontend → API → DB save → Email (Zoho SMTP via domain email).
This is exactly how real production systems work.

---

🚀 STEP 2️⃣ — Add Dependency (Zero Risk)

This step is completely safe:

• No config change yet
• No runtime impact until we wire it
• Won’t break VPS or Docker

📌 What this does (internally)

• Adds JavaMailSender
• Enables SMTP support
• Prepares Spring Boot auto-configuration

👉 Nothing executes yet — it’s just wiring capability.

---

🚀 STEP 3️⃣ — Environment Variables (SECURE + VPS-SAFE)

🧩 Goal

Inject SMTP credentials via:

.env → Docker → Spring Boot

• 👉 No hardcoding
• 👉 No secrets in GitHub
• 👉 Fully production-safe

---

✅ 3.1 — Update .env on VPS

(Our Current Architecture)
🔹 Infra Stack (vimaltech-contact-api)

• Postgres ✅
• Redis ✅
• Uses .env from:
  /opt/contact-api/.env

🔹 Deployment Stack (deployments/contact-api)

• app_blue ✅
• app_green ✅
• Both are already using:

env_file:
  - /opt/contact-api/.env

👉 This is PERFECT — centralized env management.

---

✅ 3.2 — Verify Docker Compose Uses .env

✅ Key Conclusion

👉 We DO NOT need to change Docker Compose at all

Our system is already correctly wired to support email env variables.

Add mail config there: at /opt/ location

===================
⚠️ Important Insight

Because BOTH:

• app_blue
• app_green

already use:

env_file: /opt/contact-api/.env

👉 Email config will automatically be available to BOTH containers.

• ✔ No duplication
• ✔ No config drift
• ✔ Clean DevOps practice

---

✅ 3.3 — Restart Containers (SAFE WAY)

⚠️ What Just Happened

When you ran:

cd ~/deployments/contact-api
docker compose down

Docker Compose tried to resolve variables in docker-compose.yml, like:

SPRING_DATASOURCE_URL: jdbc:postgresql://vimaltech-postgres:5432/${POSTGRES_DB}

❗ Problem

Compose does NOT read /opt/contact-api/.env automatically for variable substitution.

👉 It only auto-loads:

./.env (same directory as docker-compose.yml)

💥 Why You Saw a Warning

POSTGRES_DB variable is not set.

👉 Because Compose couldn’t find it in:

• shell env ❌
• local .env in deployment folder ❌

---

✅ FIX (Clean & Production-Safe)

1. Best for your setup below ✅
2. Explicitly tell Compose where .env is:
3. Use this command instead:

docker compose --env-file /opt/contact-api/.env down
docker compose --env-file /opt/contact-api/.env up -d

✔️ Why this works

Now Compose can:

• Resolve ${POSTGRES_DB} ✅
• Resolve ${POSTGRES_USER} ✅
• Resolve ${POSTGRES_PASSWORD} ✅

✅ Verification (MANDATORY)

Run:

docker exec -it vimaltech-contact-api-blue env | grep MAIL

and:

docker exec -it vimaltech-contact-api-green env | grep MAIL
✅ Expected

MAIL_HOST=smtp.zoho.com
MAIL_PORT=587
MAIL_USERNAME=vimal.patel@vimaltech.dev
MAIL_FROM=vimal.patel@vimaltech.dev
MAIL_PASSWORD=8gbXXXXXXXZ1

👉 “MAIL vars visible in container.”

🔐 Security Check (Critical but We Did This Right)

Make sure:

• .env is NOT committed to GitHub
• In .gitignore:

.env

========================
Using:

/opt/contact-api/.env

👉 This is excellent practice

• Outside repo
• Not exposed to GitHub
• Shared across services

---

✅ Finally done;

• Add variables to .env
• Ensure env_file exists in Docker Compose
• Restart containers
• Verify env inside container

---

🔥 Important Distinction (Critical for Interviews too)

Feature	Purpose
env_file: in compose	Injects env INTO container
--env-file flag	Helps Compose resolve ${} variables

👉 We are now using both correctly✔️

---

⚠️ Why This Matters

Without --env-file:

• Compose breaks variable substitution ❌
• I get warnings (like you saw)

Without env_file::

• App won’t see variables ❌

👉 I fixed BOTH sides correctly.

---

✅ Current Status (Checkpoint)

I now have:

• ✅ SMTP credentials inside container
• ✅ Docker config stable
• ✅ No breaking changes to the running system

[vimal-tech-dev]

🚀 STEP 4️⃣ — Spring Boot Mail Configuration

🧠 Strategy

We will:

• ✅ Add mail config non-invasively
• ✅ Bind to our existing MAIL_* env variables
• ✅ Keep everything inside the prod profile
• ❌ Do not touch DB / Redis config

---

⚠️ Important Notes

• ${MAIL_*} → already available via Docker ✅
• No hardcoding → production-safe ✅
• No impact until we use EmailService ✅

[vimal-tech-dev]

Check my PR #43.

[vimal-java-dev]

✅ Current Status

You now have:

.env → Docker → Spring Boot config → JavaMailSender ready

⏭️ Next Step

---

Now we move to the actual implementation:

📦 STEP 5️⃣ — Create Email Service Layer

• Create interface + implementation
• Keep it clean (SOLID principles)
• Prepare for async + logging

[vimal-java-dev]

🚀 STEP 4️⃣ — Spring Boot Mail Configuration

🧠 Strategy

We will:

• ✅ Add mail config non-invasively
• ✅ Bind to our existing MAIL_* env variables
• ✅ Keep everything inside the prod profile
• ❌ Do not touch DB / Redis config

⚠️ Important Notes

• ${MAIL_*} → already available via Docker ✅
• No hardcoding → production-safe ✅
• No impact until we use EmailService ✅

🧠 What This Confirms

Everything is now correctly wired:

✅ Infra Layer

• Docker networking → correct
• Env variables → injected properly
• Redis auth → working
• DB → connected

✅ Deployment Layer

• Blue/Green switching → working
• NGINX routing → working
• Health check → stable

✅ Spring Boot Layer

• Mail config → safe & non-breaking
• Actuator → fully healthy

[vimal-tech-dev]

🚀 STEP 4️⃣ — Spring Boot Mail Configuration

🧠 Strategy
We will:

• ✅ Add mail config non-invasively
• ✅ Bind to our existing MAIL_* env variables
• ✅ Keep everything inside the prod profile
• ❌ Do not touch DB / Redis config

⚠️ Important Notes

• ${MAIL_*} → already available via Docker ✅
• No hardcoding → production-safe ✅
• No impact until we use EmailService ✅

🧠 What This Confirms

Everything is now correctly wired:

✅ Infra Layer

• Docker networking → correct
• Env variables → injected properly
• Redis auth → working
• DB → connected

✅ Deployment Layer

• Blue/Green switching → working
• NGINX routing → working
• Health check → stable

✅ Spring Boot Layer

• Mail config → safe & non-breaking
• Actuator → fully healthy

🔥 This Is a Big Milestone

We now have:

Production-grade backend system:
- CI/CD pipeline ✅
- Blue/Green deployment ✅
- Health-check-driven rollout ✅
- Externalized config (.env) ✅
- Observability (Actuator + Prometheus) ✅

👉 This is real-world backend engineering, not tutorial level anymore.

[vimal-tech-starter]

✅ Current Status

You now have:

.env → Docker → Spring Boot config → JavaMailSender ready

⏭️ Next Step

Now we move to the actual implementation:

📦 STEP 5️⃣ — Create Email Service Layer

• Create interface + implementation
• Keep it clean (SOLID principles)
• Prepare for async + logging

Can you assign step five?