Skip to content

Documentation

Leaving Mailtruss.

You can take your data, your domain and your integration with you at any time, with no exit fee. This is how, in the order you will need it.

What stays yours

  • Your message history, contacts, templates, suppression list and domain settings are yours, and you can read all of them through the API.
  • Your domain stays yours. Mailtruss only asks you to publish DNS records under it, and you can delete them whenever you like.
  • The libraries (Node.js, Python, Go, PHP, Ruby, Java and .NET) and the MCP server are MIT licensed. The send call is plain HTTPS and an SMTP relay at smtp.mailtruss.com, so nothing ties your code to a proprietary protocol.
  • There is no exit fee. Cancel from Billing: a paid plan stays active until the end of the period you paid for. A founding member who cancels before the first charge pays nothing.

Why this page exists

Mailtruss is run by one person, with no uptime commitment. If email is critical to your product, you should be able to leave in an afternoon, or keep a second provider ready. Everything below is written so you can.

Export your data

Export before you delete anything: sent-email history is kept for 7 days on Free, 30 on Starter, 60 on Pro and 90 on Business, and received mail is deleted 30 days after it arrives.

WhatHow
Sent emailsDashboard: Emails, then Export, for a CSV of up to 10,000 rows (id, time, status, from, subject, delivery id, error) filtered the way the list is. API: GET /emails returns each message with its HTML and text, and GET /emails/:id/events returns its event trace.
Suppression listGET /suppressions. Carry this over. The addresses that bounced or complained must go into your next provider, or you will pay for it in reputation.
Contacts, segments, topicsGET /contacts, /segments, /topics. Contacts include tags and whether they unsubscribed: import the unsubscribed ones as suppressed.
TemplatesGET /templates lists them and GET /templates/:id returns the HTML, text and variables. Templates use {{variable}} placeholders with simple each and if blocks; your next provider may need them rendered by your own code.
Broadcasts and their statsGET /broadcasts.
Domains and their DNS recordsGET /domains/:id returns the records. You will delete them at the end, not copy them.
WebhooksGET /webhooks lists your endpoints and the events they receive. Signing secrets are not for copying: create new ones at the next provider.
Received mailGET /inbound, with /inbound/:id/raw and its attachments. Export it within 30 days.
Audit logDashboard: Settings, then Audit log, then Export (CSV).
Your own account dataDashboard: Account, then Data, then Download (JSON).
API keysKeys are shown once and stored only as a one-way hash, so they cannot be exported. Create new ones where you are going.

Anything that cannot be reached through the dashboard or the API, you can ask for under your data rights (see Your rights in the Privacy Policy) at privacy@mailtruss.com.

Save everything with one script

This script reads every list above with a full-access key and writes one JSON file for each. It pages through all of your emails, waits when it is rate limited, and fetches the full template and domain records. It needs Node 18 or later and changes nothing in your account. It was run against a real Mailtruss API before it was put here.

mailtruss-export.mjs
// Saves your Mailtruss data as JSON files. Needs Node 18 or later and a full-access API key.
// MAILTRUSS_API_KEY=ms_live_... node mailtruss-export.mjs [folder]
import { mkdir, writeFile } from "node:fs/promises";
​
const BASE = process.env.MAILTRUSS_URL ?? "https://mailtruss.com/api/v1";
const KEY = process.env.MAILTRUSS_API_KEY;
if (!KEY) throw new Error("Set MAILTRUSS_API_KEY to a full-access key");
const OUT = process.argv[2] ?? "mailtruss-export";
​
async function get(path) {
for (let attempt = 0; attempt < 6; attempt++) {
const r = await fetch(BASE + path, { headers: { Authorization: `Bearer ${KEY}` } });
if (r.status === 429) { await new Promise((ok) => setTimeout(ok, (Number(r.headers.get("ratelimit-reset")) || 1) * 1000 + 100)); continue; }
if (!r.ok) throw new Error(`${path}: ${r.status} ${await r.text()}`);
return r.json();
}
throw new Error(`${path}: still rate limited after 6 tries`);
}
​
// Emails and logs page with `after` (the last id you saw); contacts and suppressions page with `page`; the rest return everything at once.
async function everything(path, paging) {
const rows = [];
for (let page = 1, after; ; page++) {
const q = paging === "after" ? `?limit=100${after ? `&after=${after}` : ""}` : paging === "page" ? `?limit=100&page=${page}` : "";
const j = await get(path + q);
rows.push(...j.data);
if (!j.has_more || !j.data.length) return rows;
after = j.data.at(-1).id;
}
}
​
// Lists return a summary. Templates (HTML and variables) and domains (the DNS records) need one more request each for the full record.
const parts = [["emails", "/emails", "after"], ["contacts", "/contacts", "page"], ["suppressions", "/suppressions", "page"], ["segments", "/segments"], ["topics", "/topics"], ["templates", "/templates", undefined, true], ["broadcasts", "/broadcasts"], ["domains", "/domains", undefined, true], ["webhooks", "/webhooks"]];
await mkdir(OUT, { recursive: true });
for (const [name, path, paging, full] of parts) {
let rows = await everything(path, paging);
if (full) rows = await Promise.all(rows.map((r) => get(`${path}/${r.id}`)));
await writeFile(`${OUT}/${name}.json`, JSON.stringify(rows, null, 2));
console.log(`${name}: ${rows.length}`);
}

Move your sending domain without downtime

You do not have to choose a day. The records Mailtruss asks for are separate from the ones another provider asks for, so both can sit on the same domain while you move traffic over.

  • Add the new provider first. Verify the same sending domain there. Its DKIM records have different names from ours (each provider signs with its own selectors), so they do not collide.
  • Keep one SPF record per host. Mailtruss publishes its SPF on the return-path subdomain (send by default), not on your root domain. If the new provider also wants SPF on a host you already use, merge the two include: entries into a single record. Two SPF records on one host make SPF fail.
  • Move the suppression list into the new provider before it sends anything.
  • Send a small share (5 to 10%) through the new provider and compare bounce and complaint rates for a few days. A new provider starts with no reputation for you, so raise volume in steps, as we ask new Mailtruss accounts to.
  • Switch the rest and update your webhook handler (see below).
  • Remove our records last, after a week or two, and delete the domain in Mailtruss. Your DMARC record stays: it belongs to your domain.
What to delete at the end
# After the new provider has carried all your mail for a week or two, delete these at your DNS host.
# Use the exact names the domain's page in Mailtruss shows. The defaults look like this:
# <token1>._domainkey.mail.example.com CNAME three records
# send.mail.example.com MX the return path
# send.mail.example.com TXT the return-path SPF
# Leave _dmarc.mail.example.com alone: DMARC is yours, not ours.

Change the API calls

In your codeWhat to do
Send callOne POST /api/v1/emails with from, to, subject, html or text, and optional cc, bcc, reply_to, headers, tags and attachments. Map each field to your next provider's name for it. Their send docs will list the same fields under their own spelling.
IdempotencyMailtruss de-duplicates on the Idempotency-Key header. Keep the same discipline at the next provider, or de-duplicate in your own code.
Scheduling and batchesscheduled_at (up to 30 days ahead) and /emails/batch (up to 100) are ours. If you use them, find the equivalent or schedule in your own queue.
TemplatesExport them (above) and render in your code, or recreate them at the new provider.
WebhooksMailtruss signs events with the Standard Webhooks scheme (webhook-id, webhook-timestamp, webhook-signature) and names them like email.delivered and email.bounced. Change the signature check and map the event names. Run both handlers until the old events stop arriving.
SMTPIf an app sends through smtp.mailtruss.com, change the host, port and credentials. Nothing else in the app changes.
SandboxAn ms_test_ key catches mail in an inbox. Use your next provider's test mode, or point your tests at a local mail catcher.

Keep a second provider ready

The most reliable way to depend on any email provider, including this one, is to be able to leave at short notice. Put your sending behind one function, keep a second provider verified on your domain, and send a trickle of mail through it so its reputation is warm. A timed-out request may already have been accepted, so retry it with the same Idempotency-Key before you switch.

send-email.js
// Send through Mailtruss. Switch to your other provider only when Mailtruss is clearly not accepting mail.
async function sendEmail(message, idempotencyKey) {
for (let attempt = 0; attempt < 3; attempt++) {
try {
const res = await fetch("https://mailtruss.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.MAILTRUSS_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
body: JSON.stringify(message),
signal: AbortSignal.timeout(8000),
});
if (res.ok) return { provider: "mailtruss", ...(await res.json()) };
if (res.status < 500 && res.status !== 429) throw new Error(`Mailtruss refused the request: ${res.status}`); // your request is wrong: switching provider will not help
} catch (err) {
if (String(err).startsWith("Error: Mailtruss refused")) throw err;
// A timeout or a dropped connection: the request may already have been accepted, so retry with the SAME key. Mailtruss returns the first result instead of sending twice.
}
await new Promise((done) => setTimeout(done, 500 * 2 ** attempt));
}
return otherProvider.send(message); // after three tries. A duplicate is now possible, which is the price of not losing the message.
}

Also keep a recent copy of your suppression list. A scheduled run of the script above does that.

Close the account

  • Cancel the plan from Billing. It stays active until the end of the period you paid for, and you are not charged again.
  • Revoke your API keys and delete your webhook endpoints once nothing uses them.
  • Delete the organization in Settings. Access and sending stop at once. Your data is not erased at that moment: write to privacy@mailtruss.com from the owner's address and we erase it, in any case within 30 days of a verified request, except what the law requires us to keep (the Privacy Policy lists it).
  • Remove the DNS records as above.

Questions while you move, or a case this page does not cover? Write to hello@mailtruss.com and say what you are moving to. See Support for what to include.

Last updated

Something wrong or unclear on this page?

Report an issue