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

Source: https://srvscripts.com/guides/mailbaby-rest-api/
Updated: 2026-10-03
Publisher: srvScripts (https://srvscripts.com/)

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.

In short: 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…

**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](/guides/mailbaby-spf-record-domain-verification/).

## 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](/guides/mailbaby-compromised-account-delisting/).

## 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)](https://www.rfc-editor.org/rfc/rfc5321), [Linux man pages](https://man7.org/linux/man-pages/).

**Related guides:** [Managing WordPress with DirectAdmin’s WordPress Manager and wp-cli](https://srvscripts.com/guides/directadmin-wordpress-manager-wp-cli/) · [Enable SSH on ESXi and the 40 esxcli commands every VMware admin needs](https://srvscripts.com/guides/esxcli-commands-esxi/) · [What changed in cPanel 136: unified SSL, Ruby removed, Ubuntu 22.04 dropped, MariaDB 11.8](https://srvscripts.com/guides/what-changed-in-cpanel-136/).

## Frequently asked questions

### Can I send mail through the MailBaby API without setting up SMTP?

Yes. `POST /mail/send` takes a JSON body with from, to, subject and body, and the advanced endpoint adds arrays for recipients, custom headers and base64 attachments. The from domain must be authorised with a `_mailbaby` TXT record first, and the API is subject to the same hourly cap and content rules as SMTP.

### How long does MailBaby keep sending logs?

Sixty days. The log endpoint returns the same records as the portal, including the spam score for rejected messages, and accepts `startDate`, `endDate`, sender filters and `skip` and `limit` pagination, so a helpdesk macro can pull a sender’s recent history for a ticket.

### Should I automate delisting through the blocks API?

No. There is a delete call to clear a block, but using it before the compromise is cleaned up gets the address re-blocked and lengthens the next hold. Automate detection with the poller and leave the delist as a manual step after remediation.