Introduction
If your Node.js app sends emails locally but production delivery becomes unreliable, the issue is often not your code. It is usually missing production setup: verified domains, safe API key handling, retries that do not spam users, and logs that prove what happened.
This checklist is for SaaS and development teams sending password resets, invoices, OTPs, and system alerts. It focuses on what to configure before go-live, what to log for support and debugging, and how to avoid common deliverability mistakes that quietly hurt inbox placement.
The goal is simple: make email sending predictable under real traffic, easy to troubleshoot, and safe to operate across staging and production. Start with MailCub Documentation and send a verified test email from Node.js so you can confirm authentication and logs are working end-to-end.
Quick Answer
- Verify your From domain (SPF/DKIM first, DMARC when ready) before sending to real users.
- Store API keys only on the server and rotate them when needed.
- Use a queue and retries for transient failures, but do not retry permanent bounces.
- Log a message ID or request ID so support can trace “email not received” reports.
- Add event handling for bounces, failed, and deferred outcomes to keep your sending reputation clean.
Why It Matters
Transactional email is part of product reliability. If password resets or invoices fail, users lose trust, support load increases, and conversion drops.
The biggest production difference is not only SMTP vs API. It is observability and control. You need to know whether the provider accepted the message, whether it bounced, whether the domain was blocked, or whether you hit a quota.
The provided content notes that MailCub logs include statuses like Success, Failed, Deferred, and Bounced, plus API response codes and rate guidance. That is exactly the kind of signal you want during incidents. Use MailCub Documentation and the Transactional Email page as your operational references.
Node.js Transactional Email Production Setup Checklist
Use these steps in order. Each step is short on purpose and designed to be reused before launch and after major changes.
1) Separate staging and production identities
Use different domains or subdomains for staging and production. Do not let staging traffic affect your production sending identity with test patterns.
Keep From addresses consistent inside each environment (for example, staging and production should not share the same sender identity). This reduces confusion and keeps reputation isolated.
2) Verify your From domain before sending
Complete DNS setup early. SPF and DKIM are the baseline, and DMARC becomes the enforcement layer after you confirm everything is aligned and stable.
The provided content notes that MailCub treats domain verification as a first-class requirement and can return domain verification errors. Build your process around that reality and verify before rollout using MailCub Documentation.
3) Lock down API key handling (server-only)
Never place API keys in frontend code. Load secrets from the server environment, a secret manager, or protected CI/CD variables.
The provided content notes that MailCub requires an API key for requests and documents the authentication header pattern. Treat this key like a database password and keep it server-side only.
4) Use a single send wrapper in your Node.js code
Do not scatter email API calls across your codebase. Create one send module that does all of the following:
- validates inputs
- adds correlation IDs
- applies retry rules
- logs provider results
The provided content also notes that MailCub Documentation includes the send endpoint and Node usage patterns (including a Node package option). Keep your integration centralized so changes are safer and debugging is easier.
5) Implement retries only for transient failures
Retries should be targeted and controlled:
- Retry timeouts and temporary provider or network issues.
- Do not retry bounces, invalid recipients, or blocked domains.
- If you hit rate limits, back off and queue instead of retrying aggressively.
The provided content notes a MailCub rate guideline (15 requests/second) and quota-related responses. This is where queueing and backoff protect both your users and your deliverability.
Add this early by following MailCub Documentation, and review the Transactional Email page for operational visibility features like logs and events.
6) Add idempotency to prevent duplicate emails
Production failures happen: timeouts, retries, restarts, and partial crashes. Without idempotency, users may get duplicate OTPs, receipts, or alerts.
A simple pattern from the provided content is to build an idempotency key (for example, type:userId:referenceId), store it with a TTL, and skip sending if the same key already exists. This prevents duplicates during retries and queue reprocessing.
7) Log what support will ask for
At minimum, log the following for each send:
- recipient
- subject or template name
- environment
- correlation ID
- provider response code
- timestamp
The provided content notes that MailCub dashboard logs include recipient, subject, delivery status, timestamps, and error message fields. That maps directly to what support and engineering need to investigate “email not received” reports using MailCub Documentation.
8) Handle bounces and failed delivery outcomes
You do not need advanced tooling to start, but you do need a clear policy:
- stop sending to repeated hard-bounce addresses
- track failed and deferred patterns by recipient domain
- escalate auth or domain errors quickly
The provided content notes that MailCub logs expose statuses like Success, Failed, Deferred, and Bounced, and recommends monitoring bounce and complaint rates as a best practice. Use those signals to protect your domain reputation over time.
Production Checklist Table
| Checklist item | Why it matters | How to verify |
|---|---|---|
| From domain verified (SPF/DKIM; DMARC when ready) | Prevents spoofing and improves inbox placement | Provider dashboard shows domain verified; test email passes auth checks |
| API key server-only | Prevents key leaks and abuse | No keys in client bundles; keys only in server env/secrets |
| Queue + retry rules | Prevents drops during spikes | Simulate provider outage; queue drains without duplicates |
| Rate-limit handling | Avoids throttling and send loops | Backoff on 429 and queue; respects provider rate guidance |
| Idempotency keys | Prevents duplicate OTP/receipts | Force timeout; only one email sent per idempotency key |
| Logs + correlation ID | Makes “email not received” debuggable | Support can find message by userId/requestId quickly |
| Bounce handling/suppression | Protects domain reputation | Hard bounces stop after threshold; repeated failures alert |
| Staging isolation | Avoids damaging production reputation | Staging uses separate From domain/subdomain |
Common Mistakes
- Using the same From domain for staging and production
- Storing API keys in frontend code or public repositories
- Retrying everything, including permanent failures, and spamming invalid inboxes
- Not storing a correlation ID, so support cannot trace outcomes
- Ignoring rate limits until the first traffic spike
- Mixing OTP, receipts, and marketing-style content with no separation
Troubleshooting
If you get 401 (Unauthorized)
Your API key is missing or invalid. Confirm the authentication header and make sure the correct key is being used for the correct environment.
If you get 403 (Domain not verified) or 404 (Domain not found)
Your From domain is not verified or not associated with the account. Complete DNS verification and make sure your From address matches the verified domain. Use MailCub Documentation to verify the expected setup.
If you get 429 (Rate limit or quota exceeded)
Back off, queue messages, and reduce concurrency. The provided content also suggests considering plan capacity if monthly limits are being reached. Treat 429 as a queueing and pacing issue, not a reason to spam retries.
If logs show Deferred or Bounced
Treat this as a deliverability signal:
- check recipient domain patterns
- reduce retries for that segment
- suppress repeat failures
The provided content notes that MailCub logs clearly show these statuses, which should guide your next action instead of guesswork.
FAQ
What is the safest way to send transactional email from Node.js in production?
Use a verified domain, keep API keys server-only, send through a queue with safe retries, and log a correlation ID for every message.
Do I need SPF, DKIM, and DMARC for transactional email?
SPF and DKIM are the baseline. DMARC is recommended after you are confident in alignment and ready for stronger enforcement.
How do I prevent duplicate OTP or invoice emails?
Use idempotency keys with TTL storage and avoid retrying permanent failures.
What should I log to debug “email not received”?
Log recipient, template name or subject, correlation ID, provider response code, and delivery status from logs.
What does “Domain not verified” mean?
It means the From domain is not verified in the provider account, so sending is blocked until verification is completed.
How should I handle rate limits?
Queue sends, reduce concurrency, and back off on 429 responses. The provided content notes that MailCub Documentation includes rate and response code guidance for this.
Conclusion
Production email success is mostly discipline: verify your domain, protect API keys, queue sends, and keep logs that prove what happened. If you implement this checklist once, you avoid the common “works locally, breaks in production” problem and your team can answer delivery questions with confidence.
Use MailCub Documentation for setup, verification, API behavior, and logs, and use the Transactional Email page for product capabilities like delivery logs and webhook support.