Transactional emails are the plumbing of a SaaS product: password resets, login codes, onboarding messages, invoices, and critical alerts. When they arrive late or do not arrive at all, users churn, support tickets increase, and the product feels unreliable even when the app itself is working.
This guide is for SaaS and development teams who want a clean, production-ready setup for transactional email API usage: how to authenticate the sending domain, integrate an email API safely, track delivery events, and troubleshoot failures using logs instead of guessing.
You will learn a step-by-step setup that works whether you are sending a few hundred emails per day or scaling much higher. The focus is practical operations: domain authentication, server-side API usage, delivery logs, event tracking, safe retries, and clear troubleshooting paths.
For implementation and setup details, use the MailCub Documentation, review the Transactional Email product page, and check MailCub Pricing when you are ready to choose a plan.
Quick Answer (do this first)
- Verify your domain (SPF/DKIM, ideally DMARC) before sending resets or OTPs at scale.
- Keep API keys server-side only; never ship them to the browser.
- Use provider logs and event tracking to debug missing emails quickly.
- Implement retries only for transient failures (429/5xx), not config/auth errors (401/403).
- If volume and reputation are critical, plan for dedicated infrastructure later (dedicated IP/server).
Why it matters
In SaaS, transactional emails directly affect revenue and retention. If password resets fail, users cannot log in. If invoices do not arrive, payment disputes increase. If onboarding emails land in spam, activation drops.
A solid transactional setup does not promise 100% inbox placement. What it gives you is control: authenticated sending domains, consistent sending behavior, clear API responses, delivery logs, and event signals such as delivered, bounced, or blocked. That turns email into a measurable system instead of a black box.
Step-by-step solution
1) Choose your sending model: API vs SMTP
SMTP can work, but APIs are usually a better starting point for SaaS teams because they provide more structured responses, easier event tracking, and better observability. API-first sending is typically easier to scale and easier to debug during incidents.
| Decision point | SMTP | Email API |
|---|---|---|
| Debugging failures | Often harder (less structured feedback) | Easier (status codes + response payloads) |
| Event tracking | Limited unless you add extra tooling | Common (webhooks / delivery events) |
| Implementation effort | Simple for basic setups | Simple and scalable for SaaS workflows |
| Best for | Small internal systems | SaaS apps (resets, OTPs, receipts, alerts) |
2) Set up your sending domain
Do not skip domain setup. Add the domain you will send from (for example, a consistent noreply or support address) and complete verification first. At minimum, configure SPF and DKIM. DMARC is also recommended so you can improve trust and reduce spoofing risk over time.
This is one of the most common places teams create avoidable deliverability issues. A good API integration will not fix a poorly authenticated domain.
3) Create an API key and store it safely
Generate an API key from your provider dashboard and store it only on the server side (environment variables or a secret manager). Never expose the send key in frontend code.
Use the MailCub Documentation as the source of truth for API key usage and request authentication.
4) Send your first email using the API
MailCub provides a transactional send endpoint with header-based authentication. The documented format is:
POST https://api.mail.mailcub.com/api/send_email Content-Type: application/json x-sh-key: YOUR_API_KEY { "to": "user@example.com", "from": "noreply@yourdomain.com", "subject": "Reset your password", "html": "<p>Click to reset…</p>", "text": "Click to reset…" }Implementation tip: wrap sending in one backend function or worker so logs, retries, and templates are handled in one place instead of being scattered across controllers and services.
5) Add email types and templates
Create a small, controlled list of transactional message types so you do not end up with inconsistent sending behavior. Typical examples:
- password_reset
- email_verification
- login_otp
- welcome
- receipt
- critical_alert
Each type should use a consistent sender identity, a predictable subject style, both HTML and plain-text content, and an internal correlation ID stored in your database/logs.
6) Add observability: logs, analytics, and event tracking
Your team should be able to answer these questions quickly:
- Did we send it?
- What response did the provider return?
- Was it delivered, bounced, deferred, or blocked?
This is where logs and event tracking matter most. Use Documentation for integration guidance, and the Transactional Email product for operational visibility features such as logs and webhook/event support.
7) Handle rate limits and spikes safely
If your SaaS sends bursts (signups, imports, notifications, or billing runs), queue your sends and retry only when retrying makes sense.
Practical retry rules:
- Retry transient failures (timeouts, 429, 5xx)
- Use exponential backoff (1s → 2s → 4s)
- Do not retry auth/config problems (401, 403, 404) — fix configuration instead
Queueing and controlled retries protect deliverability and reduce noisy incidents during traffic spikes.
8) Scale when needed (dedicated IP / dedicated server)
Once volume grows or sender reputation becomes a core operational dependency, dedicated infrastructure may be worth considering. This is usually a scaling decision, not a day-one requirement.
The Transactional Email product page is the right place to review available options, and MailCub Pricing helps you evaluate plan fit as your sending volume grows.
Common mistakes
- Sending from an unverified domain (SPF/DKIM not configured properly).
- Putting the API key in frontend code, where it can leak.
- Using too many random “From” identities across different domains.
- Skipping the plain-text part and sending HTML-only messages.
- Retrying every error type, which wastes quota and hides real problems.
Troubleshooting
401 Unauthorized
The API key is missing or invalid. Confirm the correct header is being sent and make sure your server is loading environment variables correctly.
403 Forbidden
This usually points to domain/auth constraints such as a domain not being verified or a sender address that is not allowed. Re-check domain verification and the From address.
404 Not found / invalid route
Confirm you are calling the correct endpoint and not using the wrong environment URL. Use the endpoint documented in MailCub Documentation.
429 Rate limit / quota issues
Queue sends, slow bursts, and review your limits. If traffic spikes are normal, add pacing and backoff to keep sending stable.
“Sent” but user did not receive it
Check provider logs and events first, then verify SPF/DKIM/DMARC setup, and review subject/content patterns. Delivery logs and event timelines help you narrow down whether the issue is acceptance, delay, bounce, or inbox placement.
FAQ
What is transactional email in SaaS?
Transactional email is triggered by user actions or system events, such as password resets, verification emails, receipts, and alerts, rather than marketing campaigns.
Is an email API better than SMTP for SaaS apps?
Often yes, because APIs usually provide clearer responses, easier event tracking, and better observability for debugging at scale.
How do I authenticate my sending domain?
Add SPF and DKIM records for your domain, and DMARC if possible. This helps recipients trust your email stream and reduces spoofing risk.
How do I keep my email API key secure?
Store it server-side only (environment variables or a secret manager). Never call the provider send endpoint directly from the browser.
What logs should I store for transactional emails?
At minimum store user ID, message type, recipient, timestamp, provider status code, and a correlation ID so you can match application logs with provider logs/events.
What should I do when I hit rate limits?
Queue sends, reduce burst concurrency, and retry with exponential backoff only for transient failures such as 429 or 5xx responses.
Conclusion
A SaaS-grade transactional email system is mostly about fundamentals: authenticated domains, server-side API sending, clear logging, event tracking, and safe retry behavior. Build these pieces once, and password resets, OTPs, and receipts become predictable workflows instead of mysterious support tickets.
Start with the Transactional Email product, follow the MailCub Documentation for API setup and integration, and use MailCub Pricing when you are ready to scale.