SDKs

There is a client for TypeScript and one for Python. Each has one method for each endpoint that a program uses, and each raises an error that holds the code, the message and the fix of the API.

TypeScript and JavaScript

The client is in the mxgate npm package, the same package as the CLI and the local MCP server. It needs Node.js 20 or later and has the types of each answer.

npm install mxgate

import { createClient, ApiError } from "mxgate";

const mxgate = createClient({ apiKey: process.env.MXGATE_API_KEY });

const { domain } = await mxgate.addDomain("example.com");
for (const r of domain.records) console.log(r.type, r.name, r.value);

const { verified } = await mxgate.verifyDomain("example.com");
if (verified) await mxgate.setAlias("example.com", "*", ["you@gmail.com"]);

try {
  await mxgate.send({ from: "Ada <ada@example.com>", to: "client@example.org", subject: "Hello", text: "Hi" });
} catch (err) {
  if (err instanceof ApiError) console.error(err.body.error, err.message, err.body.fix);
}

createClient takes apiKey, apiUrl and fetchImpl. The methods are: signup, account, keys, recoverKey, confirmRecovery, rotateKey, checkout, billingPortal, listDomains, addDomain, getDomain, verifyDomain, removeDomain, listAliases, setAlias, removeAlias, listDestinations, addDestination, sendAs, createSmtpCredential, removeSmtpCredential, send, logs, notifications, setNotifications, testWebhook, apps, removeApp and status.

The package also exports setupDomain, which writes the DNS records at Cloudflare, Vercel or Porkbun, and checkDomain, which reads the mail DNS of a domain with no account.

Python

The client needs Python 3.9 or later and has no dependencies.

pip install mxgate

from mxgate import Mxgate, MxgateError

mx = Mxgate()  # the key comes from MXGATE_API_KEY, or pass api_key="mxg_..."

domain = mx.add_domain("example.com")["domain"]
for r in domain["records"]:
    print(r["type"], r["name"], r["value"])

if mx.verify_domain("example.com")["verified"]:
    mx.set_alias("*@example.com", "you@gmail.com")

try:
    mx.send("Ada <ada@example.com>", "client@example.org", "Hello", "Hi")
except MxgateError as err:
    print(err.code, err.message, err.fix)

for row in mx.iter_logs(domain="example.com", status="bounced"):
    print(row["received_at"], row["recipient"], row["explanation"])

With no api_key, the client reads MXGATE_API_KEY, then the file ~/.config/mxgate/config.json that the CLI writes. A method gives the JSON of the answer as a dict; the package has TypedDict types, so an editor shows the fields. MxgateError has status, code, message, fix and retry_after_seconds.

Check a webhook call

The Python package checks the signature of a webhook call:

from mxgate import verify_webhook

ok = verify_webhook(secret, request.headers["mxgate-signature"], request.get_data())

For Node.js, Notifications and webhooks has the ten lines that do the same with node:crypto.

Other languages

The API is plain JSON over HTTPS with one header. openapi.json is an OpenAPI 3.1 document: a client generator can read it. The API reference has each endpoint, and llms.txt has the API on one page.

For an agent

An agent does not need an SDK: the MCP server has the same calls as tools, hosted at https://api.mxgate.io/mcp or local with npx mxgate mcp.