Hugging Face's logo

Spaces:
MisbahKhan
/
Capstone
Running

App Files Community
Capstone / MAILCHIMP_SETUP.md
MisbahKhan0009
all files added
6931883
preview code
|
raw
history blame contribute delete
8.76 kB

Mailchimp Setup Guide

This guide shows how to set up Mailchimp Transactional for Care People email OTP.

Last reviewed: April 1, 2026

Important

For OTP email, use Mailchimp Transactional, not the regular Mailchimp marketing campaign API.

Mailchimp says Transactional is:

  • a paid add-on available with Standard plan or higher
  • purchased in blocks of 25,000 emails per month
  • available in demo mode for first-time users

Official docs:

What you need first

  1. A Mailchimp account on Standard plan or higher.
  2. A domain email you control, for example noreply@yourdomain.com.
  3. Access to your DNS records.

Mailchimp recommends verifying and authenticating your domain. Their Help Center also notes that free mailbox providers like Gmail, Yahoo, or AOL cannot be verified/authenticated as your sending domain.

Official doc:

Step 1: Enable Mailchimp Transactional

In Mailchimp:

  1. Open Automations.
  2. Open Transactional.
  3. If you have never used it before, click Try demo.
  4. When ready, upgrade to a paid Transactional plan.
  5. Choose your monthly email block amount.

Mailchimp's help article says first-time users can start from demo mode, and paid plans are bought in monthly 25,000-email blocks.

Official doc:

Step 2: Launch the Transactional app

After enabling Transactional:

  1. Go to the Transactional page in Mailchimp.
  2. Click Launch App.
  3. This opens the Transactional/Mandrill area where API keys, templates, senders, and logs live.

Step 3: Create your API key

Mailchimp's Quick Start says to create the API key inside Transactional settings and copy it immediately because you cannot view it again later.

Steps:

  1. In the Transactional app, open Settings.
  2. Find the API Keys section.
  3. Click Create New Key.
  4. Give it a descriptive name, for example care-people-local.
  5. Copy the key immediately and store it safely.

Official doc:

Step 4: Verify your sending domain

Mailchimp says domain verification proves you control the domain and helps inbox placement.

Steps:

  1. In Mailchimp, open Account & billing.
  2. Open Domains.
  3. In Email Domains, click Add & Verify Domain.
  4. Enter an address on your domain, for example noreply@yourdomain.com.
  5. Click Send Verification Email.
  6. Open the verification email and complete the verification.

Mailchimp also recommends domain authentication and DMARC after verification.

Official doc:

Step 5: Authenticate the domain

After verification, set up Mailchimp's recommended DNS authentication records for the same domain.

Why this matters:

  • better deliverability
  • lower spam-folder risk
  • better sender reputation

From Mailchimp's verification article:

  • they recommend both verify and authenticate
  • they strongly recommend configuring DMARC

Start here:

Step 6: Choose your sender addresses

Recommended sender setup:

  • From email: noreply@yourdomain.com
  • Reply-To: support@yourdomain.com
  • From name: Care People

Avoid using:

  • personal Gmail addresses
  • Yahoo/AOL senders
  • addresses on domains you do not control

Step 7: Put the values into the backend

Update backend/.env:

MAILCHIMP_TRANSACTIONAL_ENABLED=true
MAILCHIMP_TRANSACTIONAL_API_KEY=your_real_transactional_api_key
MAILCHIMP_FROM_EMAIL=noreply@yourdomain.com
MAILCHIMP_FROM_NAME=Care People
MAILCHIMP_REPLY_TO=support@yourdomain.com

OTP_DEV_MODE=false

Notes:

  • Keep OTP_DEV_MODE=true until your Mailchimp setup is verified.
  • Once real sending works, switch it to false.
  • If MAILCHIMP_TRANSACTIONAL_ENABLED=false, the backend stays in dev fallback mode and returns OTP in the API response.

Step 8: Restart and test the backend

From backend:

npm run dev

Then test:

  1. Import care_people.postman_collection.json
  2. Set patientEmail to a mailbox you can receive
  3. Run Send Patient OTP
  4. Confirm the OTP email arrives
  5. Run Verify Patient OTP

Step 9: Test your API key directly

Mailchimp's Quick Start recommends testing with /users/ping.

PowerShell example:

$body = @{
  key = "YOUR_API_KEY"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri "https://mandrillapp.com/api/1.0/users/ping" `
  -ContentType "application/json" `
  -Body $body

Expected result:

PONG!

Official doc:

Email templates

Current status in this repo:

  • the backend currently sends OTP using inline HTML/text
  • Mailchimp templates are optional right now
  • you can still prepare templates now, then we can wire the backend to them in a follow-up step

Mailchimp's Transactional API supports both:

  • classic Transactional templates via /templates/...
  • Mailchimp Transactional templates via /mctemplates/...

The API reference also lists:

  • /messages/send-template
  • /messages/send-mc-template

Official doc:

Recommended OTP template variables

If you want us to switch to templates later, create the template around these variables:

  • OTP_CODE
  • OTP_MINUTES
  • APP_NAME
  • SUPPORT_EMAIL

Suggested subject:

Your Care People OTP is *|OTP_CODE|*

Suggested body:

<div style="font-family: Arial, sans-serif; color: #1f2937; line-height: 1.6;">
  <p>Hello,</p>
  <p>Your Care People OTP is:</p>
  <p style="font-size: 28px; font-weight: bold; letter-spacing: 4px;">*|OTP_CODE|*</p>
  <p>This code is valid for *|OTP_MINUTES|* minutes.</p>
  <p>Please do not share this code with anyone.</p>
  <p>Care People Team</p>
</div>

Template workflow options

Option A: Create templates in the Transactional app UI

Use this when:

  • non-developers may edit email copy later
  • you want Mailchimp-managed template revisions

After the template exists, we can update the backend to send through the Mailchimp template route instead of inline HTML.

Option B: Create templates through the Transactional API

Mailchimp's API reference includes endpoints for:

  • /templates/add
  • /templates/update
  • /templates/publish
  • /templates/list
  • /templates/render

Important:

  • publish the template after editing
  • Mailchimp says published content is what new sends will use

Official doc:

Suggested naming

Use a clear name like:

care-people-otp-v1

That makes it easy to version later:

  • care-people-otp-v2
  • care-people-welcome-v1
  • care-people-appointment-confirmation-v1

Troubleshooting

API ping fails

Likely causes:

  • wrong API key
  • key copied incorrectly
  • Transactional add-on not fully enabled yet

Check:

  • Transactional app Settings > API Keys
  • the /users/ping test

OTP sends in dev mode but not through Mailchimp

Check:

  • MAILCHIMP_TRANSACTIONAL_ENABLED=true
  • MAILCHIMP_TRANSACTIONAL_API_KEY is set
  • MAILCHIMP_FROM_EMAIL is set
  • OTP_DEV_MODE=false

Messages go to spam

Check:

  • domain verified
  • domain authenticated
  • DMARC configured
  • from-address is on your own domain

Verification email never arrives

Mailchimp's domain verification article suggests:

  • allow more time
  • resend to another address on the same domain
  • add accountservices@mailchimp.com to safe senders
  • allowlist Mailchimp IPs if your IT/mail server is strict

Official doc:

Recommended rollout

  1. Enable Transactional in Mailchimp.
  2. Create API key.
  3. Verify and authenticate your domain.
  4. Put real credentials in backend/.env.
  5. Keep OTP_DEV_MODE=true for the first test.
  6. Confirm live email delivery.
  7. Turn OTP_DEV_MODE=false.
  8. Optionally create and publish an OTP template.
  9. If you want, I can then switch the backend from inline HTML to template-based sending.