DEV Community

Cover image for How to Send and Track Transactional Emails in Your App with the MonkeysMail API
Jorge Peraza
Jorge Peraza

Posted on

How to Send and Track Transactional Emails in Your App with the MonkeysMail API

#api #node #backend #developers

If you’ve ever built an app that sends welcome emails, password resets, or order confirmations,

you know how tricky email delivery, tracking, and domain setup can be.

That’s where MonkeysMail comes in — a developer-first email infrastructure built to make transactional email simple, reliable, and trackable.

In this article, you’ll learn how to:

  • Send a transactional email using the MonkeysMail API
  • Personalize content with dynamic variables
  • Track opens, clicks, and unsubscribes
  • Retrieve email metrics programmatically

🧠 What Is MonkeysMail?

MonkeysMail is a developer-centric platform for sending and monitoring emails through powerful REST APIs.

It handles deliverability, DNS authentication (SPF, DKIM, DMARC), analytics, and event tracking — so you can focus on your app logic, not mail servers.

Core benefits:

  • 🚀 REST API built for speed and reliability
  • 🔐 SPF, DKIM, and DMARC verification
  • 📊 Built-in tracking for opens, clicks, and unsubscribes
  • 🎨 Template management with variable substitution
  • ⚙️ Automation for lists and segments

🔐 Step 1: Get Your API Key

Every request to the MonkeysMail API must include your API key.

It’s formatted as prefix.secret and should be passed in the X-API-Key header.

X-API-Key: pk_live_xxxxx.yyyyy
Enter fullscreen mode Exit fullscreen mode

You can generate API keys in your MonkeysMail Dashboard.

✉️ Step 2: Send Your First Transactional Email

Use the /messages/send endpoint to send emails directly to one or more recipients.

Example Request (JSON)

{
  "from": { "email": "no-reply@example.com", "name": "MyApp" },
  "to": ["user@example.com"],
  "subject": "Welcome to MyApp!",
  "html": "<h1>Hello!</h1><p>Thanks for joining MyApp 🎉</p>",
  "text": "Hello! Thanks for joining MyApp.",
  "tags": ["onboarding", "welcome"],
  "metadata": { "user_id": "12345" }
}
Enter fullscreen mode Exit fullscreen mode

Example Response (202 Accepted)

{
  "status": "queued",
  "id": "msg_20251007001",
  "accepted": ["user@example.com"]
}
Enter fullscreen mode Exit fullscreen mode

By default, messages are enqueued for optimal throughput.
To send immediately, add ?mode=sync to the request URL.

💻 Step 3: Example Integration (Node.js)

Here’s a working Node.js snippet using fetch to call the MonkeysMail API.

import fetch from "node-fetch";

const API_KEY = process.env.MONKEYSMAIL_KEY;

async function sendTransactionalEmail(to, name) {
  const res = await fetch("https://smtp.monkeysmail.com/messages/send?mode=sync", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      from: { email: "no-reply@myapp.com", name: "MyApp" },
      to: [to],
      subject: `Welcome, ${name}!`,
      html: `<h1>Hey ${name},</h1><p>We’re glad you’re here!</p>`
    })
  });

  const data = await res.json();
  console.log("Response:", data);
}

sendTransactionalEmail("user@example.com", "Alice");
Enter fullscreen mode Exit fullscreen mode

🧩 Step 4: Personalize with Templates & Variables

Instead of embedding HTML in your code, define templates in the MonkeysMail dashboard and use template_id with dynamic variables.

{
  "template_id": "tpl_welcome_v3",
  "to": ["user@example.com"],
  "variables": {
    "first_name": "Alice",
    "plan": "Pro"
  }
}
Enter fullscreen mode Exit fullscreen mode

Example template content:

<h1>Welcome, {{ first_name }}!</h1>
<p>Your current plan: {{ plan }}</p>
Enter fullscreen mode Exit fullscreen mode

This allows non-developers (like marketing teams) to edit templates safely.

📈 Step 5: Track Opens, Clicks & Unsubscribes

MonkeysMail automatically injects tracking tokens (RID) into emails.

You can track manually too, using the tracking endpoints:

Open Tracking Pixel

<img src="https://smtp.monkeysmail.com/t/o/{{RID}}.gif" width="1" height="1" style="display:none" alt="" />
Enter fullscreen mode Exit fullscreen mode

Click Tracking

<a href="https://smtp.monkeysmail.com/t/c/{{RID}}?u={{B64URL('https://myapp.com/dashboard')}}">
  Go to Dashboard
</a>
Enter fullscreen mode Exit fullscreen mode

Unsubscribe Link

<a href="https://smtp.monkeysmail.com/t/u/{{RID}}?reason=user_request">
  Unsubscribe
</a>
Enter fullscreen mode Exit fullscreen mode

✅ Templates created within MonkeysMail automatically include open/click tracking.

⚙️ Step 6: Monitor Quotas & Errors

Each plan enforces a message quota (e.g. 150/day on Starter).
Exceeding your limit returns a 429 rate_limited response.

{
  "error": "rate_limited",
  "reason": "Message quota exceeded",
  "window": "day",
  "limit": 150,
  "remaining": 0,
  "resetAt": "2025-10-08T00:00:00+00:00"
}
Enter fullscreen mode Exit fullscreen mode
Code Meaning Notes
401 Unauthorized Missing or invalid API key
403 Forbidden Missing scope
422 Invalid Request Bad JSON or validation failure
429 Rate Limited Exceeded plan quota
500 Server Error Temporary issue — retry later

🧠 Best Practices

  • Use enqueue mode for bulk sends; sync for time-critical emails.
  • Authenticate your domain with SPF, DKIM, and DMARC.
  • Include plain-text fallback for accessibility.
  • Tag messages for analytics.
  • Handle rate limits gracefully with retries after resetAt.
  • Respect unsubscribe links (CAN-SPAM & GDPR).

🧪 Quick Test with cURL 

curl -X POST "https://smtp.monkeysmail.com/messages/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MONKEYSMAIL_API_KEY" \
  -d '{
    "from": {"email": "no-reply@myapp.com", "name": "MyApp"},
    "to": ["user@example.com"],
    "subject": "Welcome!",
    "text": "Hi there",
    "html": "<p>Hi there!</p>"
  }'
Enter fullscreen mode Exit fullscreen mode

🎯 TL;DR

Feature Endpoint
Send single message /messages/send
Send to list /messages/send/list
Send to segment /messages/send/segment
Track open /t/o/{rid}.gif
Track click /t/c/{rid}?u=...
Unsubscribe /t/u/{rid}

🚀 Start Sending Today

MonkeysMail lets you integrate transactional email into your app in minutes — with tracking, templates, and scalability built in.

  1. Sign up → monkeysmail.com
  2. Verify your domain
  3. Generate an API key
  4. Start sending 🎉

Top comments (0)