Using the MailBaby REST API: sending, logs and block management

SMTP relay is the right integration for a mail server, but a hosting provider also needs programmatic access: pulling the delivery log into a ticket, alerting when an address is blocked, or sending from an application that has no local MTA. MailBaby exposes those functions through a REST API at api.mailbaby.net, currently version 1.5.0, with endpoints for sending, attachments, log retrieval and block management. This tutorial covers authentication, the endpoints most useful in a hosting operation, and a monitoring pattern we use across a fleet.

Short answer: Authenticate every request to https://api.mailbaby.net with an X-API-KEY header from the InterServer portal, authorise each from domain with a _mailbaby.<domain> TXT record, and use POST /mail/send for messages, GET /mail/log with date and sender filters for the 60-day delivery log, and GET /mail/blocks to list blocked addresses. The same 6,000 per hour per sender cap and content rules apply as for SMTP. The most useful automation is a cron job that polls the blocks endpoint every fifteen minutes and alerts on new entries.

Authentication and domain authorisation

API access uses a key issued in the InterServer portal alongside the SMTP credentials. It is sent as an X-API-KEY header on every request. Keep it out of scripts committed to version control; a leaked key can send mail as any of your authorised domains.

Sending through the API requires the from domain to be authorised for the account. The mechanism is the same _mailbaby.<domain> TXT record used for SMTP verification:

_mailbaby.example.com.  3600  IN  TXT  "v=1 user=mb12345"

Publish it, confirm with dig +short TXT _mailbaby.example.com @1.1.1.1, and the domain appears as authorised in the portal. The SPF include is still needed so recipients pass SPF; see the SPF guide.

Sending a message

The send endpoint accepts a JSON body with the usual fields. A minimal call with curl:

curl -s -X POST https://api.mailbaby.net/mail/send \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "alerts@example.com",
    "to": "ops@example.org",
    "subject": "Backup completed",
    "body": "Nightly backup finished with no errors."
  }'

A successful response returns a JSON object with a status and a message identifier that later matches the log entry. The advanced send endpoint accepts arrays for to, cc and bcc, a replyto field, custom headers and an attachments array where each attachment is a filename plus base64-encoded data. The same 6,000 messages per hour per sender address limit applies as for SMTP, and prohibited content categories are enforced identically, so the API is not a way around either.

Check the endpoint paths against the current OpenAPI specification in the portal; minor versions have moved fields between the simple and advanced send calls.

Reading the log

The log endpoint returns the same records the portal shows: timestamp, sender, recipient, subject, score and outcome, retained for 60 days. Filter by date range and sender to pull exactly what a ticket needs:

curl -s 'https://api.mailbaby.net/mail/log?startDate=2026-09-28&endDate=2026-09-29&from=info@example.com' \
  -H 'X-API-KEY: YOUR_API_KEY' | jq '.'

Paginate with the skip and limit parameters on large accounts. Because the log includes the score for rejected messages, a helpdesk macro that pulls the last twenty entries for a sender answers most “my email did not arrive” tickets without anyone logging into the portal.

Block management

The blocks endpoint lists addresses currently blocked on the account, with the reason and the time of the block:

curl -s https://api.mailbaby.net/mail/blocks \
  -H 'X-API-KEY: YOUR_API_KEY' | jq '.blocks[] | {address, reason, created}'

There is a corresponding delete call to clear a block once the underlying compromise has been fixed. Do not automate that; a delist without cleanup gets the address re-blocked and lengthens the next hold. The clean-up procedure is in the compromise and delisting guide.

A fleet monitoring pattern

The most valuable automation is a cron job that polls the blocks endpoint every fifteen minutes and raises an alert when a new address appears. A minimal shell version:

#!/bin/bash
KEY='YOUR_API_KEY'
STATE=/var/lib/mailbaby/blocks.last
mkdir -p "$(dirname "$STATE")"
curl -s https://api.mailbaby.net/mail/blocks -H "X-API-KEY: $KEY" \
  | jq -r '.blocks[].address' | sort > "$STATE.new"
if [ -f "$STATE" ]; then
  NEW=$(comm -13 "$STATE" "$STATE.new")
  [ -n "$NEW" ] && echo "New MailBaby blocks: $NEW" | mail -s "MailBaby block alert" ops@example.org
fi
mv "$STATE.new" "$STATE"

Pair it with a daily summary that counts rSPAM outcomes per sender from the log endpoint; a sender whose rejection count jumps is usually compromised before it is blocked, and catching it a few hours earlier keeps the account’s reputation intact.

Verify

After the first API send, confirm the message identifier from the response appears in the log endpoint output and that the received message’s headers show spf=pass and, if you sign locally before handing content to the API, dkim=pass. Test the block poller by comparing its output to the portal’s block page. The common pitfall is rate-limiting your own monitoring: the API applies request limits per key, and a poller running every minute across thirty servers with one shared key will start receiving 429 responses. Use one key per server or lengthen the interval.

MailBaby REST API at a glance

Official documentation: RFC 5321 (SMTP), Linux man pages.

Related guides: Managing WordPress with DirectAdmin’s WordPress Manager and wp-cli · Enable SSH on ESXi and the 40 esxcli commands every VMware admin needs · What changed in cPanel 136: unified SSL, Ruby removed, Ubuntu 22.04 dropped, MariaDB 11.8.

Frequently asked questions