Skip to content

Documentation

Migrate from Mailgun.

Mailgun takes a form with the domain in the URL; Mailtruss takes JSON with the domain in the from address. Here is the send call before and after, then what maps to what and what to check.

The send call, before and after

Before, with Mailgun's messages API (see Mailgun's docs for your library version; EU accounts use api.eu.mailgun.net):

send.js
import formData from "form-data";
import Mailgun from "mailgun.js";
​
const mg = new Mailgun(formData).client({ username: "api", key: process.env.MAILGUN_API_KEY });
await mg.messages.create("mg.yourdomain.com", {
from: "ada@yourdomain.com", to: ["you@example.com"], subject: "Hello", html: "<p>It works.</p>",
});

After, with Mailtruss:

send.ts
import { MailClient } from "mailtruss";
​
const mail = new MailClient({ apiKey: process.env.MAILTRUSS_API_KEY! });
const { id } = await mail.emails.send({ from: "ada@yourdomain.com", to: "you@example.com", subject: "Hello", html: "<p>It works.</p>" });

The changes: the body is JSON instead of a form; the sending domain is no longer in the URL, because Mailtruss reads it from the from address (it must be a domain you have verified); the key goes in an Authorization: Bearer header instead of basic authentication with the user api; and the response carries the new email's id, which you can use to fetch its delivery trace.

If you send over SMTP

Apps that use Mailgun's SMTP relay only need new settings. Mailgun's relay takes a per-domain SMTP user and password; Mailtruss takes any username with an API key as the password:

SMTP settings
host: smtp.mailgun.org
port: 587
username: postmaster@mg.yourdomain.com
password: <your Mailgun SMTP password>

Details and framework examples are on the SMTP page and in the integration guides.

What maps to what

  • to, cc, bcc: lists in Mailtruss. To send a different message to each recipient (Mailgun's recipient-variables), use POST /api/v1/emails/batch, up to 100 emails per call.
  • o:tag becomes tags, a list of name and value pairs you can filter by. h:X-My-Header becomes an entry in headers. v:my-var custom data has no direct equivalent: put what you need in tags.
  • o:tracking, o:tracking-clicks, o:tracking-opens: tracking is switched on per sending domain (off by default), and a message can switch it off through the API.
  • o:deliverytime becomes scheduled_at, an ISO 8601 time. o:testmode is replaced by sending to delivered@mailtruss.test and the other test addresses, which need no verified domain and reach no real mailbox.
  • Attachments (multipart files) become attachments with a base64 content and a filename.
  • Templates: a Mailtruss template is sent by ID with a variables object, and only the published version is ever sent. See Sending.
  • Inbound routes: turn on receiving for a verified domain, publish one MX record, and handle email.received at a webhook or read messages through the API. See Receiving email. Routes that match on rules and forward are not part of it: do the matching in your handler.
  • Mailing lists: contacts, segments, topics and broadcasts.

Webhooks

Mailgun signs its webhooks with an HMAC over a timestamp and a token, so verification code has to change. Mailtruss signs with the Standard Webhooks scheme, and the client libraries include a verifyWebhook helper. Events are named email.delivered, email.bounced, email.complained, email.opened and email.clicked, so map them in your handler. See Webhooks.

What does not carry over

  • Email validation: Mailgun sells address validation. Mailtruss has none.
  • Dedicated IP addresses and IP pools, and Mailgun's EU region: Mailtruss sends from one region on shared infrastructure.
  • Your history: sent-message logs do not move. Keep your Mailgun account for as long as you need to look things up (its log retention is short on lower plans).

A safe order to switch

  1. Create an account and verify your sending domain (DNS records). If you used a subdomain such as mg.yourdomain.com with Mailgun, its DKIM and SPF records are separate from Mailtruss's: check yours with the domain checker and avoid two SPF records on one name.
  2. Create a key and send a test to delivered@mailtruss.test, so nothing reaches a real inbox.
  3. Change the client, the key and the request in one place in your code.
  4. Point your webhook handler at the new signing secret and event names, then send real mail.
  5. Keep Mailgun active for a few days while you watch the first real sends, then switch it off.

Your daily limit while you move

A new account starts with a lower daily sending limit that grows for 14 days (day 1: 200; days 2 to 3: 500; days 4 to 7: 1,500; days 8 to 14: 5,000, then your plan's own limit). It protects your sending reputation, which you share with every other customer. Plan the switch around it: send your lowest-risk mail first, and keep your old provider on for the rest until your limit catches up.

If you cannot wait, ask for a higher limit. On a paid plan, open Sending limits in the dashboard and tell us where you are moving from, your volume and what you send. A person reviews it against checks we run ourselves (your domain's authentication, your plan, how your account has behaved) and either approves a limit, asks a question or says no, always with a reason. Approval is never automatic. We reply within 1 working day and decide within 2 working days once we have everything we need. These are targets, not guarantees. How limit reviews work.

Comparing costs first? See Mailtruss vs Mailgun, which uses Mailgun's own published prices. Mailtruss's are on the pricing page.

Last updated

Something wrong or unclear on this page?

Report an issue