{ "openapi": "3.0.3", "info": { "title": "MailBaby Email Delivery and Management Service API", "version": "1.5.0", "description": "**Send emails fast and with confidence through our easy to use [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API interface.**\n\n# Overview\n\nThis is the API interface to the [Mail Baby](https://mail.baby/) Mail services provided by [InterServer](https://www.interserver.net). To use this service you must have an account with us at [my.interserver.net](https://my.interserver.net).\n\n# Mail Orders\n\nEvery sending account in MailBaby is backed by a **Mail Order** \u2014 a provisioned sending credential with a numeric `id` and a corresponding SMTP username (`mb`). Most calls accept an optional `id` parameter; when omitted the API automatically selects the first active order on your account. Use `GET /mail` to list all orders, and `GET /mail/{id}` to inspect a single order including its current SMTP password.\n\n# Sending Email\n\nThree sending methods are available depending on your use-case:\n| Endpoint | Best for | |----------|----------| | `POST /mail/send` | Simple single-recipient messages | | `POST /mail/advsend` | Multiple recipients, CC/BCC, attachments, named contacts | | `POST /mail/rawsend` | Pre-built RFC 822 messages (e.g. DKIM-signed payloads) |\n\nAfter a successful send each endpoint returns a `GenericResponse` whose `text` field contains the **transaction ID** assigned by the relay. This ID can later be matched against entries in `GET /mail/log` via the `mailid` query parameter.\n\n# Filtering & Logs\n\n`GET /mail/log` provides paginated access to every message accepted by the relay for your account. Combine any of the query parameters to narrow results \u2014 e.g. `from`, `to`, `subject`, `messageId`, `origin`, `mx`, `startDate`/`endDate`, and `delivered`.\n\n# Blocking\n\nTwo independent mechanisms exist for suppressing unwanted email:\n- **Block lists** (`GET /mail/blocks`, `POST /mail/blocks/delete`) \u2014 addresses flagged by the\n system spam filters (LOCAL_BL_RCPT / MBTRAP rules in rspamd, and suspicious subjects).\n- **Deny rules** (`GET /mail/rules`, `POST /mail/rules`, `DELETE /mail/rules/{ruleId}`) \u2014\n custom rules you configure to reject specific senders, domains, destination addresses, or\n subject-line prefixes before a message is even attempted.\n\n\n# Authentication\n\nIn order to use most of the API calls you must pass credentials from the [my.interserver.net](https://my.interserver.net/) site.\nWe support several different authentication methods but the preferred method is to use the **API Key** which you can get from the [Account Security](https://my.interserver.net/account_security) page.\nPass your key in the `X-API-KEY` HTTP request header for every protected call.\n", "termsOfService": "https://www.interserver.net/terms-of-service.html", "contact": { "name": "Mail Baby", "url": "https://www.mail.baby/contact/", "email": "support@interserver.net" }, "license": { "name": "GNU GPLv3", "url": "https://www.gnu.org/licenses/gpl.txt" } }, "servers": [ { "url": "https://api.mailbaby.net", "description": "Live API Endpoint" } ], "paths": { "/ping": { "get": { "tags": [ "Status" ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string", "example": "Server is up and running" } }, "application/json": { "schema": { "type": "string", "example": "Server is up and running" } } }, "description": "Server is up and running" }, "default": { "description": "Something is wrong" } }, "operationId": "pingServer", "summary": "Health check \u2014 verify the API is reachable", "description": "**No authentication required.** Returns the plain-text string `Server is up and running` with a `200` status when the API host is reachable. Use this as a connectivity smoke-test before attempting any authenticated call. Useful for uptime monitoring, load-balancer health checks, and CI smoke tests.\n", "security": [] } }, "/mail": { "get": { "tags": [ "Services" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MailOrder" } }, "examples": { "MailOrders": { "value": [ { "id": 39, "status": "active", "username": "mb39" }, { "id": 33, "status": "canceled", "username": "mb33", "comment": "test order" } ] } } } }, "links": { "getMailOrderById": { "operationId": "getMailOrderById", "parameters": { "id": "$response.body#/0/id" }, "description": "The `id` value returned in the response can be used as the `id` path parameter in `GET /mail/{id}` to retrieve full order details." }, "sendMailByIdLink": { "operationId": "sendMail", "parameters": { "id": "$response.body#/0/id" }, "description": "The `id` value returned in the response can be used as the `id` body parameter in `POST /mail/send`." }, "sendAdvMailByIdLink": { "operationId": "sendAdvMail", "parameters": { "id": "$response.body#/0/id" }, "description": "The `id` value returned in the response can be used as the `id` body parameter in `POST /mail/advsend`." }, "viewMailLogByIdLink": { "operationId": "viewMailLog", "parameters": { "id": "$response.body#/0/id" }, "description": "The `id` value returned in the response can be used as the `id` query parameter in `GET /mail/log`." }, "getStatsByIdLink": { "operationId": "getStats", "parameters": { "id": "$response.body#/0/id" }, "description": "The `id` value returned in the response can be used as the `id` query parameter in `GET /mail/stats`." } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "getMailOrders", "summary": "List your provisioned mail orders (sending accounts)", "description": "Use this **before sending** if you need to discover which mail order `id` to pass to `/mail/send`, `/mail/advsend`, `/mail/rawsend`, `/mail/log`, or `/mail/stats`. Returns every mail order (active **and** canceled) on your account. Each record includes the numeric `id`, the `status` (`active` or `canceled`), the SMTP `username` (always `mb`), and an optional `comment`.\n\nThe `id` values returned here are used as the `id` input parameter on all sending endpoints (`/mail/send`, `/mail/advsend`, `/mail/rawsend`) as well as the log and stats queries. When the `id` parameter is omitted on those calls the API automatically picks the **first active** order returned by this endpoint.\n\nTo retrieve full details \u2014 including the current SMTP password \u2014 for a single order use `GET /mail/{id}`.\n" } }, "/mail/{id}": { "get": { "tags": [ "Services" ], "parameters": [ { "example": 39, "name": "id", "description": "The numeric ID of the mail order.", "schema": { "format": "int64", "type": "integer" }, "in": "path", "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailOrderDetail" }, "examples": { "MailOrderDetail": { "value": { "id": 39, "status": "active", "username": "mb39", "password": "s3cr3tpassword" } } } } }, "links": { "sendMailByIdLink": { "operationId": "sendMail", "parameters": { "id": "$response.body#/id" }, "description": "The `id` value can be used as the `id` body parameter in `POST /mail/send`." }, "sendAdvMailByIdLink": { "operationId": "sendAdvMail", "parameters": { "id": "$response.body#/id" }, "description": "The `id` value can be used as the `id` body parameter in `POST /mail/advsend`." }, "viewMailLogByIdLink": { "operationId": "viewMailLog", "parameters": { "id": "$response.body#/id" }, "description": "The `id` value can be used as the `id` query parameter in `GET /mail/log`." }, "getStatsByIdLink": { "operationId": "getStats", "description": "Use `GET /mail/stats` to view sending statistics for this mail order." } }, "description": "OK" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "getMailOrderById", "summary": "Get one mail order's full detail including SMTP password", "description": "**Returns the SMTP password** in addition to the basic `GET /mail` fields. Use when you need to authenticate against `relay.mailbaby.net:25` from an SMTP client directly. Required: `id` (path; obtain from `GET /mail`). Returns the full detail record for one specific mail order identified by its numeric `id`.\n\nThe `username` and `password` values returned here can be used directly to authenticate against `relay.mailbaby.net:25` (SMTP AUTH) if you need to send email via a native SMTP client rather than through the REST API.\n\nThe `id` path parameter is the same integer `id` value returned by `GET /mail`.\n" } }, "/mail/send": { "post": { "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendMail" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SendMail" } } }, "required": true }, "tags": [ "Sending" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "examples": { "SendSuccess": { "value": { "status": "ok", "text": "185caa69ff7000f47c" } } } } }, "links": { "lookupByTransactionId": { "operationId": "viewMailLog", "parameters": { "mailid": "$response.body#/text" }, "description": "The transaction ID in `text` can be passed as `mailid` to `GET /mail/log` to retrieve the delivery record." } }, "description": "Email accepted for delivery" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "sendMail", "summary": "Send a simple email (single recipient, plain or HTML)", "description": "**Use this for the simplest case** \u2014 one or a few plain-string recipients, no attachments, no CC/BCC, no named contacts. Required: `from`, `to`, `subject`, `body`. Optional: `id` (selects which mail order to send through; auto-selects your first active order if omitted). Sends through one of your mail orders using a flat set of fields.\n\n**HTML detection** is automatic \u2014 if the `body` value contains any HTML tags the message will be sent as `text/html`; otherwise it is sent as `text/plain`.\n\nThe `from` address is also automatically set as the `Reply-To` header.\n\n*Note*: If you need to send to multiple recipients, add CC/BCC, or include file attachments, use `POST /mail/advsend` instead. If you have a pre-built RFC 822 message (e.g. already DKIM-signed), use `POST /mail/rawsend`.\n\nOn success the response `text` field contains the relay transaction ID. This ID can be used with `GET /mail/log` (via the `mailid` query parameter) to look up the delivery record.\n" } }, "/mail/rawsend": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMailRaw" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SendMailRaw" } } }, "required": true }, "tags": [ "Sending" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "examples": { "RawSendSuccess": { "value": { "status": "ok", "text": "185caa69ff7000f47c" } } } } }, "links": { "lookupByTransactionId": { "operationId": "viewMailLog", "parameters": { "mailid": "$response.body#/text" }, "description": "The transaction ID in `text` can be passed as `mailid` to `GET /mail/log` to retrieve the delivery record." } }, "description": "Email accepted for delivery" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "rawMail", "summary": "Send a pre-built RFC 822 message verbatim (preserves DKIM)", "description": "**Use this when you have already built (and possibly DKIM-signed) the full RFC 822 message yourself** and want the relay to transmit it byte-for-byte. Required: `raw_email` (full RFC 822 string with headers + body). Optional: `id` (mail order to authenticate as). Accepts a complete, pre-built RFC 822 email message (headers + body) as a string and injects it into the relay without any modification.\n\nThis endpoint is particularly useful when the message has already been **DKIM-signed** \u2014 because the relay transmits the exact bytes you provide, the DKIM signature remains intact. If you use the other sending endpoints the relay may add or reorder headers, breaking an existing signature.\n\nThe `From` and recipient addresses are parsed automatically from the message headers (`From`, `To`, `Cc`, `Bcc`). You do **not** need to specify them separately.\n\nIf an `id` is provided it must correspond to an active mail order on your account. If omitted, the first active order is selected automatically. The SMTP credentials for the selected order are used to authenticate with the relay.\n\nOn success the response `text` field contains the relay transaction ID. This ID can be used with `GET /mail/log` (via the `mailid` query parameter) to look up the delivery record.\n" } }, "/mail/advsend": { "post": { "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendMailAdv" }, "examples": { "BasicForm": { "summary": "Simple string addresses", "value": { "subject": "Welcome", "body": "Hello", "from": "user@domain.com", "to": "support@interserver.net" } }, "NamedForm": { "summary": "RFC 822 named addresses", "value": { "subject": "Welcome", "body": "Hello", "from": "Joe ", "to": "Jane " } }, "AdvSendExample": { "summary": "Structured array with attachment", "value": { "subject": "Welcome", "body": "Hello", "from": { "email": "user@domain.com" }, "to": [ { "email": "someone@client.com", "name": "Mr Client" } ], "attachments": [ { "filename": "message.txt", "data": "aGVsbG8gdGhlcmUK" } ], "id": 66 } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/SendMailAdv" }, "examples": { "BasicJson": { "summary": "Plain string addresses", "value": { "subject": "Welcome", "body": "Hello", "from": "user@domain.com", "to": "support@interserver.net" } }, "ArrayJson": { "summary": "Structured objects", "value": { "subject": "Welcome", "body": "Hello", "from": { "name": "Joe", "email": "user@domain.com" }, "to": [ { "name": "Joe", "email": "support@interserver.net" } ] } }, "NameEmailJson": { "summary": "RFC 822 named string", "value": { "subject": "Welcome", "body": "Hello", "from": "Joe ", "to": "Joe " } }, "FullExample": { "summary": "Full-featured with CC, attachment, id", "value": { "subject": "Welcome", "body": "Hello", "from": { "email": "user@domain.com", "name": "Sender Name" }, "to": [ { "email": "someone@client.com", "name": "Mr Client" } ], "cc": [ { "email": "someone2@client.com", "name": "Mr Second" } ], "bcc": [ { "email": "archive@company.com" } ], "replyto": [ { "email": "replies@domain.com" } ], "attachments": [ { "filename": "message.txt", "data": "aGVsbG8gdGhlcmUK" } ], "id": 66 } } } } }, "required": true }, "tags": [ "Sending" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "examples": { "SendSuccess": { "value": { "status": "ok", "text": "185caa69ff7000f47c" } } } } }, "links": { "lookupByTransactionId": { "operationId": "viewMailLog", "parameters": { "mailid": "$response.body#/text" }, "description": "The transaction ID in `text` can be passed as `mailid` to `GET /mail/log` to retrieve the delivery record." } }, "description": "Email accepted for delivery" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "sendAdvMail", "summary": "Send email with multiple recipients, CC/BCC, attachments, named contacts", "description": "**Use this when the simple send is not enough** \u2014 multiple recipients, CC/BCC, named contacts, custom Reply-To, or file attachments. Required: `from`, `to`, `subject`, `body`. Optional: `cc`, `bcc`, `replyto`, `attachments` (array of `{filename,data}` with base64 data), `id`. Sends through one of your mail orders with full control over recipients, headers, and attachments.\n\n**Content-type flexibility** \u2014 the request body may be submitted as either `application/x-www-form-urlencoded` or `application/json`. When using form encoding, address fields (`from`, `to`, `replyto`, `cc`, `bcc`) accept both a plain RFC 822 comma-separated string (e.g. `\"Joe , jane@example.com\"`) and the structured `[{\"email\":\"...\",\"name\":\"...\"}]` array format. When using JSON, both formats are equally supported.\n\n**HTML detection** is automatic \u2014 if `body` contains HTML tags the `Content-Type` is set to `text/html`; otherwise `text/plain`.\n\n**Attachments** must be base64-encoded. Each attachment requires at least a `data` field; the optional `filename` field controls the attachment name shown to recipients.\n\nIf an `id` is provided it must correspond to an active mail order on your account. If omitted, the first active order is selected automatically.\n\nOn success the response `text` field contains the relay transaction ID which can be looked up in `GET /mail/log` via the `mailid` query parameter.\n\n## Examples\n\n### Form \u2014 basic string addresses\n```sh curl -X POST https://api.mailbaby.net/mail/advsend \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'subject=Welcome' \\\n -d 'body=Hello' \\\n -d from=user@domain.com \\\n -d to=support@interserver.net\n```\n### Form \u2014 RFC 822 named addresses\n```sh curl -X POST https://api.mailbaby.net/mail/advsend \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'subject=Welcome' \\\n -d 'body=Hello' \\\n -d 'from=Joe ' \\\n -d 'to=Jane '\n```\n### Form \u2014 multiple recipients as array\n```sh curl -X POST https://api.mailbaby.net/mail/advsend \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'subject=Welcome' -d 'body=Hello' \\\n -d from=user@domain.com \\\n -d 'to[0][name]=Joe' -d 'to[0][email]=support@interserver.net' \\\n -d 'to[1][name]=Jane' -d 'to[1][email]=jane@interserver.net'\n```\n### JSON \u2014 structured objects\n```sh curl -X POST https://api.mailbaby.net/mail/advsend \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"subject\": \"Welcome\",\n \"body\": \"

Hello

\",\n \"from\": {\"email\": \"user@domain.com\", \"name\": \"Sender Name\"},\n \"to\": [{\"email\": \"joe@client.com\", \"name\": \"Joe Client\"}],\n \"cc\": [{\"email\": \"manager@client.com\"}],\n \"attachments\": [{\"filename\": \"report.pdf\", \"data\": \"BASE64_DATA\"}]\n }'\n```\n" } }, "/mail/log": { "get": { "tags": [ "History" ], "parameters": [ { "example": 2604, "name": "id", "description": "The numeric ID of the mail order to filter by. When omitted, logs from the first active mail order are returned. Obtain valid IDs from `GET /mail` or `GET /mail/{id}`.", "schema": { "format": "int64", "type": "integer" }, "in": "query", "required": false }, { "example": "1.2.3.4", "name": "origin", "description": "Filter by the originating IP address from which the message was submitted to the relay. Must be a valid IPv4 or IPv6 address.", "schema": { "type": "string" }, "in": "query", "required": false }, { "example": "mx.google.com", "name": "mx", "description": "Filter by the MX hostname the relay attempted delivery to. For example `mx.google.com` would return messages destined for Gmail recipients. Maps to `mxHostname` in the `MailLogEntry` response.", "schema": { "type": "string" }, "in": "query", "required": false }, { "example": "me@sender.com", "name": "from", "description": "Filter by SMTP envelope `MAIL FROM` address (exact match). This is the address the relay used for bounce handling and may differ from the `From:` message header. For header-level filtering use `headerfrom`.", "schema": { "format": "email", "type": "string" }, "in": "query", "required": false }, { "example": "you@receiver.com", "name": "to", "description": "Filter by SMTP envelope `RCPT TO` address (exact match). This is the delivery address used by the relay and may differ from the `To:` header when BCC recipients are involved.", "schema": { "format": "email", "type": "string" }, "in": "query", "required": false }, { "example": "Your order has shipped", "name": "subject", "description": "Filter by email `Subject` header (exact match). To search for a substring, include it in the full subject text.", "schema": { "type": "string" }, "in": "query", "required": false }, { "example": "185997065c60008840", "name": "mailid", "description": "Filter by the relay-assigned mail ID string (exact match). This corresponds to the `id` field in `MailLogEntry` and to the `text` value returned by the sending endpoints on success. Format is an 18\u201319 character hexadecimal string such as `185997065c60008840`.", "schema": { "maxLength": 19, "minLength": 18, "type": "string" }, "in": "query", "required": false }, { "example": "", "name": "messageId", "description": "Filter by the `Message-ID` email header using a substring (case-insensitive) match. The `Message-ID` is assigned by the sending mail client and is visible in the `messageId` field of `MailLogEntry`. Useful when you know the message ID generated by your application but not the relay `mailid`.", "schema": { "type": "string" }, "in": "query", "required": false }, { "example": "replies@sender.com", "name": "replyto", "description": "Filter by the `Reply-To` message header address (exact match). Only returns messages where this header was explicitly set.", "schema": { "format": "email", "type": "string" }, "in": "query", "required": false }, { "example": "newsletter@sender.com", "name": "headerfrom", "description": "Filter by the `From` message header address (exact match). This is the human-visible sender address and may differ from the SMTP envelope `from` parameter when sending on behalf of another address.", "schema": { "format": "email", "type": "string" }, "in": "query", "required": false }, { "example": 1, "name": "delivered", "description": "Filter by delivery status. `1` returns only messages that were successfully delivered to the destination MX. `0` returns messages that are still queued, deferred, or failed. Omit to return all messages regardless of delivery status.", "schema": { "title": "DeliveredStatus", "enum": [ 0, 1 ], "type": "integer", "x-enum-varnames": [ "NotDelivered", "Delivered" ] }, "in": "query", "required": false }, { "example": 0, "name": "skip", "description": "Number of records to skip for pagination. Use in combination with `limit` to page through large result sets. Defaults to `0` (no skip).", "schema": { "format": "int32", "default": 0, "minimum": 0, "type": "integer" }, "in": "query", "required": false }, { "example": 100, "name": "limit", "description": "Maximum number of records to return per page. Defaults to `100`. Maximum allowed value is `10000`. The response also includes a `total` field with the full matched count so you can calculate the number of pages.", "schema": { "format": "int32", "default": 100, "maximum": 10000, "minimum": 1, "type": "integer" }, "in": "query", "required": false }, { "example": 1641781008, "name": "startDate", "description": "Earliest date to include. Accepts either a Unix timestamp (integer seconds since epoch) or a date string parseable by `strtotime()` such as `2024-01-15` or `last monday`. Messages with a `time` value **greater than or equal to** this value will be included.", "schema": { "$ref": "#/components/schemas/DateOrTimestamp" }, "in": "query", "required": false }, { "example": 1673317008, "name": "endDate", "description": "Latest date to include. Accepts either a Unix timestamp (integer seconds since epoch) or a date string parseable by `strtotime()` such as `2024-01-31` or `yesterday`. Messages with a `time` value **less than or equal to** this value will be included.", "schema": { "$ref": "#/components/schemas/DateOrTimestamp" }, "in": "query", "required": false }, { "example": "time", "name": "sort", "description": "Field to sort results by. Currently only `time` is supported (sorts by internal row ID which corresponds to chronological order).", "schema": { "default": "time", "enum": [ "time" ], "type": "string" }, "in": "query", "required": false }, { "example": "desc", "name": "dir", "description": "Sort direction. `desc` returns newest first (default), `asc` returns oldest first.", "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" }, "in": "query", "required": false }, { "example": "recipient", "name": "groupby", "description": "Controls how results are grouped. `recipient` (default) returns one row per delivery attempt \u2014 a message sent to 4 recipients produces 4 rows, each with its own `recipient`, `delivered`, `response`, and delivery metadata. `message` collapses to one row per unique message ID; delivery-level fields will reflect one arbitrary recipient per message. The `total` count in the response matches the grouping mode.", "schema": { "default": "recipient", "enum": [ "message", "recipient" ], "type": "string" }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailLog" }, "examples": { "MailLogRecipientExample": { "summary": "groupby=recipient (default) - one row per delivery attempt", "value": { "total": 4, "skip": 0, "limit": 100, "emails": [ { "_id": 103172, "id": "17c7eda538e0005d03", "from": "person@mysite.com", "to": "client@isp.com", "subject": "sell 0.005 shares", "messageId": "", "created": "2021-10-14 08:50:10", "time": 1634215809, "user": "mb5658", "transtype": "ESMTPSA", "origin": "199.231.189.154", "interface": "feeder", "sendingZone": "interserver", "bodySize": 63, "seq": 1, "delivered": 1, "code": 250, "recipient": "client@isp.com", "domain": "interserver.net", "locked": 1, "lockTime": "1634215818533", "assigned": "relay1", "queued": "2021-10-14T12:50:15.487Z", "mxHostname": "mx.j.is.cc", "response": "250 2.0.0 Ok queued as C91D83E128C" } ] } }, "MailLogMessageExample": { "summary": "groupby=message - one row per message", "value": { "total": 1, "skip": 0, "limit": 100, "emails": [ { "_id": 103172, "id": "17c7eda538e0005d03", "from": "person@mysite.com", "to": "client@isp.com", "subject": "sell 0.005 shares", "messageId": "", "created": "2021-10-14 08:50:10", "time": 1634215809, "user": "mb5658", "transtype": "ESMTPSA", "origin": "199.231.189.154", "interface": "feeder", "sendingZone": "interserver", "bodySize": 63, "seq": 1, "delivered": 1, "code": 250, "recipient": "client@isp.com", "domain": "interserver.net", "locked": 1, "lockTime": "1634215818533", "assigned": "relay1", "queued": "2021-10-14T12:50:15.487Z", "mxHostname": "mx.j.is.cc", "response": "250 2.0.0 Ok queued as C91D83E128C" } ] } } } } }, "links": { "delistSenderBlock": { "operationId": "delistBlock", "parameters": { "email": "$response.body#/emails/0/from" }, "description": "A `from` address returned in the log can be passed as `email` to `POST /mail/blocks/delete` to remove a block on that sender." } }, "description": "Paginated list of mail log entries" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "viewMailLog", "summary": "Query the mail delivery log (filterable, paginated)", "description": "**Use this to find or audit sent messages.** All filters are optional and combinable. The most useful filters: `mailid` (the transaction id returned by a send call), `from` / `to` (envelope addresses), `subject`, `messageId` (case-insensitive substring on the `Message-ID` header), `delivered` (`1`=delivered, `0`=queued/failed), and the `startDate`/`endDate` date range. Returns a paginated list of every email message accepted by the relay for your mail account(s).\n\n**Row grouping** is controlled by the `groupby` parameter. By default (`groupby=recipient`), the response contains one row per delivery attempt \u2014 so a single message sent to 4 recipients produces 4 rows, each with its own `recipient`, `delivered`, `response`, and `mxHostname` values. Set `groupby=message` to collapse to one row per message (delivery fields will reflect one arbitrary recipient).\n\n**Pagination** is controlled by `skip` and `limit`. The `total` in the response reflects the row count **after** grouping, so it matches the number of pages you need to fetch.\n\n**Date filtering** accepts either a Unix timestamp (integer) or a date string parseable by PHP `strtotime()` such as `2024-01-15`, `last monday`, or `2024-01-01 00:00:00`. Examples: `startDate=1704067200&endDate=1706745599` or `startDate=2024-01-01&endDate=2024-01-31`.\n\n**Sorting** is controlled by `sort` and `dir`. Currently the only sort key is `time` (default), which orders by internal row ID.\n\n**Delivery status** can be filtered with the `delivered` parameter: `delivered=1` returns only successfully delivered messages; `delivered=0` returns messages still in queue or that failed.\n\n**Address filtering** distinguishes between the SMTP envelope address (`from`, `to`) and message headers (`headerfrom` for the `From:` header, `replyto` for `Reply-To:`). These may differ when a message is sent on behalf of another address.\n\nThe `mailid` parameter corresponds to the `id` field in the returned `MailLogEntry` objects, **not** the `_id` field. It also matches the transaction ID returned in the `text` field of a successful send response from `/mail/send`, `/mail/advsend`, or `/mail/rawsend`.\n\nThe `messageId` parameter searches the `Message-ID` email header (case-insensitive substring match).\n" } }, "/mail/stats": { "get": { "tags": [ "History" ], "parameters": [ { "name": "time", "description": "The time window to scope `received`, `sent`, and `volume` statistics. Does not affect `usage` or `cost`, which are always calculated over the current billing cycle. Defaults to `1h`.", "schema": { "default": "1h", "enum": [ "all", "billing", "month", "7d", "24h", "day", "1h" ], "x-enum-varnames": [ "All", "Billing", "Month", "SevenDays", "TwentyFourHours", "Day", "OneHour" ], "type": "string" }, "in": "query", "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailStatsType" }, "examples": { "StatsExample": { "value": { "time": "all", "usage": 55, "currency": "USD", "cost": 1.02, "received": 508, "sent": 495, "volume": { "to": { "client@domain.com": 395, "user@site.net": 57 }, "from": { "billing@somedomain.com": 369 }, "ip": { "1.1.1.1": 142, "2.2.2.2": 132 } } } } } } }, "links": { "viewMailLogLink": { "operationId": "viewMailLog", "description": "Use `GET /mail/log` to view individual message details behind the aggregate statistics." } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "getStats", "summary": "Account usage, cost, and volume statistics for a time window", "description": "**Use this for dashboards or billing-cycle reviews.** Returns aggregate sending statistics for your mail account(s). The `time` query param controls the window for `received`, `sent`, and `volume` (`1h`, `24h`, `7d`, `month`, `day`, `billing`, `all`). The `usage` and `cost` fields are always for the current billing cycle, regardless of `time`.\n\nThe response includes:\n- **`usage`** \u2014 total messages accepted by the relay during the current billing\n cycle (used for cost calculation).\n- **`cost`** \u2014 estimated cost for the billing cycle based on the base plan price\n plus per-email charges.\n- **`received`** / **`sent`** \u2014 count of messages accepted by the relay /\n successfully delivered to the destination MX within the selected `time` window.\n- **`volume`** \u2014 top-500 breakdown of message counts grouped by source IP (`ip`),\n destination address (`to`), and sender address (`from`) within the selected window.\n\n\n**Time windows** (controlled by the `time` parameter):\n| Value | Window | |-------|--------| | `1h` | Last 1 hour (default) | | `24h` | Last 24 hours | | `7d` | Last 7 days | | `month` | Current calendar month (1st to now) | | `day` | Today (midnight to now) | | `billing` | Current billing cycle (last invoice date to next invoice date) | | `all` | All time |\n" } }, "/mail/blocks": { "get": { "tags": [ "Blocking" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailBlocks" }, "examples": { "MailBlocksExample": { "value": { "local": [ { "date": "2023-08-07", "from": "user@domain.com", "messageId": "pFaRqFUEWkucjhTuIzYuoAgWU@domain.com", "subject": "Test Email", "to": "['client@site.com']" } ], "mbtrap": [ { "date": "2023-08-07", "from": "user@domain.com", "messageId": "pFaRqFUEWkucjhTuIzYuoAgWU@domain.com", "subject": "Test Email", "to": "['client@site.com']" } ], "subject": [ { "from": "user@domain.com", "subject": "Test Email" } ] } } } } }, "links": { "delistBlockLink": { "operationId": "delistBlock", "parameters": { "email": "$response.body#/local/0/from" }, "description": "The `from` address in any block list entry can be passed as the `email` field to `POST /mail/blocks/delete` to delist it." } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "getMailBlocks", "summary": "List addresses currently flagged by spam-filter block lists", "description": "**Use this to discover which addresses to delist.** The `from` value of any returned entry can be passed to `POST /mail/blocks/delete` (as the `email` field) to remove the block. Returns addresses and messages that have been flagged by the spam filtering system for your mail account(s). Three categories are returned:\n\n- **`local`** \u2014 messages flagged by the `LOCAL_BL_RCPT` rspamd rule. These are\n messages sent to recipients on your account's local block list.\n- **`mbtrap`** \u2014 messages flagged by the `MBTRAP` rspamd rule. These are messages\n that triggered MailBaby's internal trap / honeypot detection.\n- **`subject`** \u2014 senders whose recent messages contain spam-indicative subjects\n (strings containing `@`, `smtp`, `socks4`, or `socks5`) with high repetition\n (more than 4 identical subjects from the same sender in the last 3 days).\n\n\nThe `local` and `mbtrap` results cover the last 5 days. The `subject` results cover the last 3 days.\n\nA sender address returned in any of these lists can be delisted using `POST /mail/blocks/delete` with the `email` field set to that address.\n" } }, "/mail/blocks/delete": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddressParam" }, "examples": { "BlocksDeleteExample": { "value": { "email": "client@domain.com" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/EmailAddressParam" }, "examples": { "BlocksDeleteExampleForm": { "value": { "email": "client@domain.com" } } } } }, "required": true }, "tags": [ "Blocking" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "examples": { "DelistSuccess": { "value": { "status": "ok", "text": "record deleted" } } } } }, "description": "Address successfully delisted" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "delistBlock", "summary": "Delist an email address from the spam-filter block lists", "description": "**Destructive \u2014 wipes block records for the given address.** Required: `email` (must be a valid address; typically a `from` value previously returned by `GET /mail/blocks` or `GET /mail/log`). Delists an email address from all three block list stores:\n1. The rspamd spam-filter database (`fromemail` / envelope sender records). 2. The MailChannels integration block table. 3. The MailBaby internal block table.\n\nUse `GET /mail/blocks` to discover which addresses are currently blocked. The `from` field in any returned block entry is a valid input for this call.\n\n**Note:** Delisting an address removes it from the block tracking databases but does not prevent the spam filter from re-blocking it if future messages continue to trigger filter rules.\n" } }, "/mail/rules": { "get": { "tags": [ "Blocking" ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DenyRuleRecord" } }, "examples": { "ExampleMailRulesList": { "value": [ { "id": "14", "user": "mb20682", "type": "email", "data": "domeinwo@server.guesshost.net", "created": "2022-03-22 19:16:35" }, { "id": "15", "user": "mb20682", "type": "domain", "data": "guesshost.net", "created": "2022-03-22 19:18:01" } ] } } } }, "links": { "deleteRuleLink": { "operationId": "deleteRule", "parameters": { "ruleId": "$response.body#/0/id" }, "description": "The `id` value returned in the response can be used as the `ruleId` path parameter in `DELETE /mail/rules/{ruleId}`." } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "getRules", "summary": "List custom deny rules (sender / domain / destination / prefix)", "description": "**Use this to inspect or pick a `ruleId` to delete.** Returns all deny rules you have configured for your active mail account(s). Deny rules are evaluated **before** a message is transmitted and cause it to be rejected immediately when it matches.\n\nFour rule types are supported:\n| `type` | `data` format | Effect | |--------|---------------|--------| | `email` | `user@domain.com` | Rejects any message from this exact sender address | | `domain` | `domain.com` | Rejects any message from any address at this domain | | `destination` | `user@domain.com` | Rejects any message addressed to this recipient | | `startswith` | `prefix` | Rejects any message whose sender address begins with this string (alphanumeric, `+`, `_`, `.`, `-` only) |\n\nUse `POST /mail/rules` to add new rules and `DELETE /mail/rules/{ruleId}` to remove them. The `id` field in each returned record is the value needed for the delete call.\n" }, "post": { "requestBody": { "description": "Fields required to create a new email deny rule.", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DenyRuleNew" }, "examples": { "DenyEmailForm": { "summary": "Block a specific sender", "value": { "type": "email", "data": "spammer@badactor.net" } }, "DenyDomainForm": { "summary": "Block an entire domain", "value": { "type": "domain", "data": "badactor.net" } }, "DenyStartsWithForm": { "summary": "Block sender prefix", "value": { "type": "startswith", "data": "noreply-spam" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/DenyRuleNew" }, "examples": { "DenyRuleNewJsonExample": { "value": { "user": "mb20682", "type": "email", "data": "domeinwo@server.guesshost.net" } } } } }, "required": true }, "tags": [ "Blocking" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "examples": { "AddRuleSuccess": { "value": { "status": "ok", "text": "42" } } } } }, "links": { "deleteCreatedRule": { "operationId": "deleteRule", "parameters": { "ruleId": "$response.body#/text" }, "description": "The rule `id` returned in `text` can be passed as `ruleId` to `DELETE /mail/rules/{ruleId}` to remove this rule." } }, "description": "Rule created successfully" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "addRule", "summary": "Create a deny rule to block a sender, domain, destination, or prefix", "description": "**Use this to prevent future relay attempts that match a pattern.** Required: `type` (`email`, `domain`, `destination`, or `startswith`) and `data` (the value to match). Optional: `user` (SMTP username; auto-selects first active order if omitted). Adds a deny rule to block specific senders, domains, destinations, or sender prefixes from being relayed through your mail account.\n\nThe `type` field selects the matching strategy:\n- **`email`** \u2014 exact match against the SMTP envelope `MAIL FROM` address. - **`domain`** \u2014 matches any sender address at the specified domain. - **`destination`** \u2014 exact match against the SMTP envelope `RCPT TO` address. - **`startswith`** \u2014 matches any sender address whose local-part (the portion\n before the `@`) starts with the given string. Only alphanumeric characters\n and `+`, `_`, `.`, `-` are permitted in the prefix.\n\n\nIf `username` is provided it must be the SMTP username of one of your active mail orders (e.g. `mb20682`). If omitted the rule is associated with your first active order.\n\nOn success the response `text` field contains the newly created rule's `id`, which can later be passed to `DELETE /mail/rules/{ruleId}` to remove it.\n" } }, "/mail/rules/{ruleId}": { "delete": { "tags": [ "Blocking" ], "parameters": [ { "examples": { "RuleIdExample": { "value": 34 } }, "name": "ruleId", "description": "The numeric ID of the deny rule to delete. Obtain this from the `id` field in `GET /mail/rules` or the `text` field of a `POST /mail/rules` response.", "schema": { "type": "integer" }, "in": "path", "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "examples": { "DeleteSuccess": { "value": { "status": "ok", "text": "record deleted" } } } } }, "description": "Rule deleted successfully" }, "400": { "$ref": "#/components/responses/BadInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "deleteRule", "summary": "Delete a deny rule by its numeric ruleId", "description": "**Destructive \u2014 permanently removes the rule.** Required: `ruleId` (path param; obtain from the `id` field returned by `GET /mail/rules` or the `text` field returned by `POST /mail/rules`). Permanently removes a single deny rule identified by its numeric `ruleId`.\n\nThe `ruleId` is the `id` field returned by `GET /mail/rules` or the `text` field from a successful `POST /mail/rules` response.\n\nOnly rules belonging to your own active mail account(s) can be deleted \u2014 the server will reject attempts to delete rules that belong to a different account.\n" } } }, "components": { "schemas": { "SendMailTo": { "oneOf": [ { "title": "EmailAddressSingle", "format": "email", "description": "Single recipient email address.", "type": "string", "example": "johndoe@company.com" }, { "title": "EmailAddressList", "description": "Multiple recipient email addresses.", "type": "array", "items": { "format": "email", "type": "string" }, "example": [ "johndoe@company.com", "janedoe@company.com" ] } ], "title": "SendMailTo", "description": "The primary recipient address for a simple send request. Accepts a single email address string or an array of email address strings for multiple recipients.", "example": "johndoe@company.com" }, "GenericResponse": { "title": "GenericResponse", "description": "Standard success response returned by write operations (send, add rule, delete, etc.). The `status` field is always `\"ok\"` on success. The `text` field carries operation-specific data \u2014 for sending calls it contains the relay transaction ID; for create calls it contains the new record's ID; for delete calls it contains a confirmation string.", "required": [ "status", "text" ], "type": "object", "properties": { "status": { "description": "Always `\"ok\"` on success.", "type": "string", "example": "ok" }, "text": { "description": "Operation-specific result string. For send operations this is the relay transaction ID (e.g. `185caa69ff7000f47c`) which can be used as the `mailid` parameter in `GET /mail/log`. For create operations this is the new record's numeric ID. For delete operations this is a human-readable confirmation.", "type": "string", "example": "185caa69ff7000f47c" } } }, "ErrorMessage": { "title": "ErrorMessage", "description": "The response body returned when an error occurs.", "required": [ "code", "message" ], "type": "object", "properties": { "code": { "format": "int32", "description": "The HTTP-style status code associated with the error.", "type": "integer", "example": 400 }, "message": { "description": "A human-readable description of the error.", "type": "string", "example": "The specified ID was invalid." } }, "example": { "code": 400, "message": "There was an error." } }, "MailOrder": { "title": "MailOrder", "description": "A mail service order record. Each order represents one provisioned sending account with a dedicated SMTP username. The `id` is the numeric identifier used across most API calls. The `username` is always `mb` and is the SMTP AUTH username for `relay.mailbaby.net`.", "required": [ "status", "id", "username" ], "type": "object", "properties": { "id": { "format": "int32", "description": "The unique numeric ID of the mail order. Used as the `id` parameter on sending calls, log queries, and stats queries.", "type": "integer", "example": 21472 }, "status": { "description": "The current order status. Only `active` orders can be used for sending. `canceled` orders are retained for history but cannot send.", "enum": [ "active", "canceled" ], "type": "string", "example": "active" }, "username": { "description": "The SMTP AUTH username for this order, always in the format `mb`. Use together with the password from `GET /mail/{id}` to authenticate directly against `relay.mailbaby.net:25` if needed.", "pattern": "^mb\\d+$", "type": "string", "example": "mb21472" }, "comment": { "description": "Optional human-readable note associated with the order. Only present in the response when the order has a non-empty comment.", "type": "string" } }, "example": { "id": 21472, "status": "active", "username": "mb21472" } }, "MailOrderDetail": { "title": "MailOrderDetail", "description": "Extended mail order record including the current SMTP password. Returned by `GET /mail/{id}`. The `username` and `password` fields can be used to authenticate directly against `relay.mailbaby.net:25` via SMTP AUTH if you prefer to send via a native SMTP client rather than the REST API.", "allOf": [ { "$ref": "#/components/schemas/MailOrder" }, { "title": "MailOrderPassword", "required": [ "password" ], "type": "object", "properties": { "password": { "description": "The current SMTP AUTH password for this mail order. Use with the `username` field to authenticate against `relay.mailbaby.net:25`.", "type": "string", "example": "s3cr3tpassword" } } } ], "example": { "id": 21472, "status": "active", "username": "mb21472", "password": "s3cr3tpassword" } }, "EmailAddressName": { "title": "EmailAddressName", "description": "An email contact with an optional display name. Used in structured address fields (`from`, `to`, `cc`, `bcc`, `replyto`) in `SendMailAdv`.", "required": [ "email" ], "type": "object", "properties": { "email": { "format": "email", "description": "The email address.", "type": "string", "example": "user@domain.com" }, "name": { "description": "Optional display name shown to recipients (e.g. in the `From:` header).", "type": "string", "example": "John Smith" } }, "example": { "email": "user@domain.com", "name": "John Smith" } }, "EmailAddressNames": { "title": "EmailAddressNames", "description": "An array of email contacts, each with an email address and optional display name.", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressName" }, "example": [ { "email": "user@domain.com", "name": "John Smith" } ] }, "EmailAddressParam": { "title": "EmailAddressParam", "description": "A single email address parameter used as the body of `POST /mail/blocks/delete`.", "required": [ "email" ], "type": "object", "properties": { "email": { "format": "email", "description": "The email address to delist from all block lists.", "type": "string", "example": "user@domain.com" } }, "example": { "email": "user@domain.com" } }, "EmailAddressesTypes": { "oneOf": [ { "title": "EmailAddressString", "description": "A single email address or RFC 822 comma-separated list. Example: `\"joe@example.com\"` or `\"Joe , jane@example.com\"`.", "type": "string", "example": "Joe " }, { "$ref": "#/components/schemas/EmailAddressNames" } ], "title": "EmailAddressesTypes", "description": "A flexible email address list that accepts either a plain RFC 822 string or a structured array of contact objects. When a string is provided it is parsed as a comma-separated list of RFC 822 addresses (supporting the `\"Name \"` and bare `email` formats). When an array is provided each entry must have at least an `email` field with an optional `name` field." }, "EmailAddressTypes": { "oneOf": [ { "title": "EmailAddressSingleString", "description": "A single email address or RFC 822 named-address string. Example: `\"user@domain.com\"` or `\"Joe \"`.", "type": "string", "example": "Joe " }, { "$ref": "#/components/schemas/EmailAddressName" } ], "title": "EmailAddressTypes", "description": "A flexible single email address that accepts either a plain address string, an RFC 822 named-address string (`\"Name \"`), or a structured contact object." }, "SendMail": { "title": "SendMail", "description": "Request body for `POST /mail/send`. Sends a simple single-recipient message. HTML detection is automatic \u2014 if `body` contains HTML tags the message is sent as `text/html`; otherwise as `text/plain`. The `from` address is automatically set as both the `From` and `Reply-To` headers.\n\nFor multiple recipients, CC/BCC, attachments, or per-field Reply-To control, use `POST /mail/advsend` instead.", "required": [ "to", "from", "subject", "body" ], "type": "object", "properties": { "to": { "$ref": "#/components/schemas/SendMailTo" }, "from": { "format": "email", "description": "The sender address. This is used as both the `From` header and the `Reply-To` header automatically. Must be a valid email address authorized for your mail order.", "type": "string", "example": "janedoe@company.com" }, "subject": { "description": "The subject line of the email.", "type": "string", "example": "Attention Client" }, "body": { "description": "The email body. If the string contains any HTML tags the message is automatically sent as `text/html`; otherwise it is sent as `text/plain`.", "type": "string", "example": "This is an email to inform you that something noteworthy happened." }, "id": { "format": "int64", "description": "Optional numeric ID of the mail order to send through. If omitted the first active order on your account is used automatically. Valid IDs are returned by `GET /mail`.", "type": "integer", "example": 2604 } }, "example": { "to": "johndoe@company.com", "from": "janedoe@company.com", "subject": "Attention Client", "body": "This is an email to inform you that something noteworthy happened." } }, "SendMailAdv": { "title": "SendMailAdv", "description": "Request body for `POST /mail/advsend`. Provides full control over all email headers and supports multiple recipients, CC, BCC, Reply-To, and file attachments.\n\nAddress fields (`from`, `to`, `replyto`, `cc`, `bcc`) each accept either a plain RFC 822 string (e.g. `\"Joe \"` or a comma-separated list) or a structured array of `{\"email\": \"...\", \"name\": \"...\"}` objects.\n\nHTML detection is automatic based on whether `body` contains HTML tags.", "required": [ "from", "to", "subject", "body" ], "type": "object", "properties": { "subject": { "description": "The subject line of the email.", "type": "string", "example": "Your Package has been Delivered!" }, "body": { "description": "The email body. If the string contains any HTML tags the message is automatically sent as `text/html`; otherwise it is sent as `text/plain`.", "type": "string", "example": "The package you ordered on 2021-01-23 has been delivered." }, "from": { "description": "The sender address. Accepts a plain email string, an RFC 822 named string (`\"Name \"`), or a `{\"email\": \"...\", \"name\": \"...\"}` object.", "allOf": [ { "$ref": "#/components/schemas/EmailAddressTypes" } ] }, "to": { "description": "One or more destination addresses. Accepts a comma-separated RFC 822 string or an array of contact objects.", "allOf": [ { "$ref": "#/components/schemas/EmailAddressesTypes" } ] }, "replyto": { "description": "Optional. One or more addresses to set as the `Reply-To` header. When recipients reply to the message their email client will address the reply to these addresses instead of `from`.", "allOf": [ { "$ref": "#/components/schemas/EmailAddressesTypes" } ] }, "cc": { "description": "Optional. Carbon-copy recipients. These addresses are listed in the `Cc` header and are visible to all recipients.", "allOf": [ { "$ref": "#/components/schemas/EmailAddressesTypes" } ] }, "bcc": { "description": "Optional. Blind-carbon-copy recipients. These addresses receive the message but are not listed in any visible header.", "allOf": [ { "$ref": "#/components/schemas/EmailAddressesTypes" } ] }, "attachments": { "description": "Optional list of file attachments. Each file must be base64-encoded. Include `filename` so recipients see a meaningful attachment name.", "type": "array", "items": { "$ref": "#/components/schemas/MailAttachment" } }, "id": { "format": "int64", "description": "Optional numeric ID of the mail order to send through. If omitted the first active order on your account is used automatically. Valid IDs are returned by `GET /mail`.", "type": "integer", "example": 5000 } }, "example": { "subject": "Welcome", "body": "Hello", "from": "user@domain.com", "to": "someone@client.com", "cc": [ { "email": "someone2@client.com", "name": "Mr Client" } ], "attachments": [ { "filename": "file.txt", "data": "aGVsbG8gdGhlcmUK" } ], "id": 66 } }, "SendMailRaw": { "title": "SendMailRaw", "description": "Request body for `POST /mail/rawsend`. Accepts a complete RFC 822 message (all headers and body) as a verbatim string. The relay injects it without modification, preserving any existing `DKIM-Signature` header intact.\n\nThe `From`, `To`, `Cc`, and `Bcc` addresses are extracted from the message headers automatically \u2014 you do not need to specify them separately.", "required": [ "raw_email" ], "type": "object", "properties": { "raw_email": { "description": "The complete RFC 822 email message including all headers and the body. Must include at minimum `From`, `To`, `Subject`, `Date`, and `MIME-Version` headers. DKIM signatures in the `DKIM-Signature` header are transmitted verbatim and will pass verification at the destination.", "type": "string" }, "id": { "format": "int64", "description": "Optional numeric ID of the mail order to use for SMTP authentication. If omitted the first active order on your account is used. Valid IDs are returned by `GET /mail`.", "type": "integer" } }, "example": { "id": 39, "raw_email": "Date: Sun, 16 Nov 2025 14:30:11 -0500\nTo: Me \nFrom: Mail Test \nReply-To: Mail Test \nSubject: testing out raw email api call\nMessage-ID: <9jeLkYQIw7KqYnoiCnnYj7EC0IrSHdp8XMuJq9a5qs@interserver.net>\nMIME-Version: 1.0\nContent-Type: text/plain; charset=utf-8\nDKIM-Signature: v=1; d=interserver.net; s=my; a=rsa-sha256; ...\n\nThis is a test of the rawsend API call.\n" } }, "MailAttachment": { "title": "MailAttachment", "description": "A file attachment for use with `POST /mail/advsend`. The file content must be base64-encoded. The `filename` is shown to recipients in their email client.", "required": [ "data", "filename" ], "type": "object", "properties": { "filename": { "description": "The filename shown to recipients (e.g. `report.pdf`, `invoice.xlsx`).", "type": "string", "example": "message.txt" }, "data": { "format": "byte", "description": "The file contents as a base64-encoded string. Decode this to retrieve the original binary file.", "type": "string", "example": "aGVsbG8gdGhlcmUK" } }, "example": { "filename": "file.txt", "data": "aGVsbG8gdGhlcmUK" } }, "MailBlocks": { "title": "MailBlocks", "description": "The complete set of blocked addresses and message patterns returned by `GET /mail/blocks`. Three independent block sources are combined into one response. Use `POST /mail/blocks/delete` with a `from` address from any entry to delist it.", "required": [ "local", "mbtrap", "subject" ], "type": "object", "properties": { "local": { "description": "Messages flagged by the `LOCAL_BL_RCPT` rspamd rule in the last 5 days. These are messages sent to recipients on a local block list.", "type": "array", "items": { "$ref": "#/components/schemas/MailBlockClickHouse" } }, "mbtrap": { "description": "Messages flagged by the `MBTRAP` rspamd rule in the last 5 days. These triggered MailBaby's honeypot / trap address detection.", "type": "array", "items": { "$ref": "#/components/schemas/MailBlockClickHouse" } }, "subject": { "description": "Senders whose messages contained spam-indicative subjects (containing `@`, `smtp`, `socks4`, or `socks5`) with more than 4 occurrences of the same subject in the last 3 days.", "type": "array", "items": { "$ref": "#/components/schemas/MailBlockRspamd" } } } }, "MailBlockClickHouse": { "title": "MailBlockClickHouse", "description": "A block event record sourced from the ClickHouse analytics store. Represents a message that triggered one of the rspamd block rules (`LOCAL_BL_RCPT` or `MBTRAP`). The `from` address can be passed to `POST /mail/blocks/delete` to delist it.", "required": [ "date", "from", "subject", "to" ], "type": "object", "properties": { "date": { "format": "date", "description": "The date the block event was recorded.", "type": "string", "example": "2023-08-07" }, "from": { "description": "The SMTP envelope sender (`MAIL FROM`) address of the blocked message. Pass this value as `email` to `POST /mail/blocks/delete` to delist it.", "type": "string", "example": "user@domain.com" }, "messageId": { "nullable": true, "description": "The `Message-ID` header of the blocked message, or `null` if not present.", "type": "string", "example": "pFaRqFUEWkucjhTuIzYuoAgWU@domain.com" }, "subject": { "description": "The `Subject` header of the blocked message.", "type": "string", "example": "Test Email" }, "to": { "description": "The serialized list of recipients of the blocked message.", "type": "string", "example": "['client@site.com']" } }, "example": { "date": "2023-08-07", "from": "user@domain.com", "messageId": "pFaRqFUEWkucjhTuIzYuoAgWU@domain.com", "subject": "Test Email", "to": "['client@site.com']" } }, "MailBlockRspamd": { "title": "MailBlockRspamd", "description": "A block pattern sourced from the rspamd database. Represents a sender whose recent messages contained suspicious subject lines (e.g. containing relay/proxy strings) repeated more than 4 times in the last 3 days. The `from` address can be passed to `POST /mail/blocks/delete` to delist it.", "required": [ "subject", "from" ], "type": "object", "properties": { "from": { "description": "The sender email address. Pass this value as `email` to `POST /mail/blocks/delete` to delist the sender.", "type": "string", "example": "user@domain.com" }, "subject": { "description": "The suspicious subject pattern that triggered the block.", "type": "string", "example": "Test email" } }, "example": { "from": "user@domain.com", "subject": "Test email" } }, "DenyRuleRecord": { "title": "DenyRuleRecord", "description": "A complete deny rule record as returned by `GET /mail/rules`. Combines the rule definition fields (`DenyRuleNew`) with server-assigned metadata (`id` and `created`). The `id` value is required by `DELETE /mail/rules/{ruleId}`.", "allOf": [ { "title": "DenyRuleMetadata", "required": [ "id", "created" ], "type": "object", "properties": { "id": { "description": "The numeric ID of the deny rule, as a string. Pass this as `ruleId` to `DELETE /mail/rules/{ruleId}` to remove the rule.", "type": "string", "example": "41124" }, "created": { "format": "date-time", "description": "The timestamp when the rule was created.", "type": "string", "example": "2022-03-22 19:16:35" } } }, { "$ref": "#/components/schemas/DenyRuleNew" } ], "example": { "id": "14", "user": "mb20682", "type": "email", "data": "domeinwo@server.guesshost.net", "created": "2022-03-22 19:16:35" } }, "DenyRuleNew": { "title": "DenyRuleNew", "description": "The fields required to create a new email deny rule via `POST /mail/rules`. The `type` controls what `data` is matched against:\n- `email` \u2014 exact sender address match - `domain` \u2014 all senders from a domain - `destination` \u2014 exact recipient address match - `startswith` \u2014 sender local-part prefix match (alphanumeric + `+_.-` only)", "required": [ "type", "data" ], "type": "object", "properties": { "user": { "description": "Optional SMTP username of the mail order to associate this rule with (e.g. `mb20682`). If omitted the first active order is used. Valid usernames are the `username` values returned by `GET /mail`.", "type": "string", "example": "mb20682" }, "type": { "description": "The matching strategy for this rule. `email` blocks an exact sender address, `domain` blocks all senders at a domain, `destination` blocks an exact recipient address, and `startswith` blocks any sender whose local-part begins with the given prefix.", "enum": [ "domain", "email", "startswith", "destination" ], "type": "string", "example": "email" }, "data": { "description": "The value to match against, interpreted according to `type`: a full email address for `email`/`destination`, a domain name for `domain`, or an alphanumeric prefix string for `startswith`.", "type": "string", "example": "domeinwo@server.guesshost.net" } }, "example": { "user": "mb20682", "type": "email", "data": "domeinwo@server.guesshost.net" } }, "MailLog": { "title": "MailLog", "description": "Paginated mail log response returned by `GET /mail/log`. Contains the full matched count (`total`) plus a page of `MailLogEntry` records. Use `skip` and `limit` to page through large result sets.", "required": [ "total", "skip", "limit", "emails" ], "type": "object", "properties": { "total": { "description": "Total number of log entries that match the supplied filters, regardless of `skip` and `limit`. Use this to calculate the number of pages: `ceil(total / limit)`.", "type": "integer", "example": 10234 }, "skip": { "description": "The `skip` value used for this page (echoed from the request).", "type": "integer", "example": 0 }, "limit": { "description": "The `limit` value used for this page (echoed from the request).", "type": "integer", "example": 100 }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/MailLogEntry" } } } }, "MailLogEntry": { "title": "MailLogEntry", "description": "A single email record in the mail log. Combines data from the message store (envelope metadata), the queue release table (delivery status and response), and the sender delivery table (MX routing details).\n\nKey field relationships with other API calls:\n- The `id` field matches the `mailid` query parameter on `GET /mail/log` and\n the `text` field of a successful send response.\n- The `from` address can be passed to `POST /mail/blocks/delete` to delist a\n flagged sender.\n- The `user` field is the SMTP username (e.g. `mb5658`) corresponding to the\n `username` field in `GET /mail` / `GET /mail/{id}`.", "required": [ "_id", "id", "from", "to", "created", "time", "user", "transtype", "origin", "interface" ], "type": "object", "properties": { "_id": { "description": "Internal auto-increment database row ID. Not meaningful outside the API.", "type": "integer", "example": 103172 }, "id": { "description": "The relay-assigned mail ID (18\u201319 hex characters). This is the value returned as `text` by the sending endpoints and accepted as the `mailid` filter on `GET /mail/log`.", "maxLength": 19, "minLength": 18, "type": "string", "example": "17c7eda538e0005d03" }, "from": { "description": "SMTP envelope `MAIL FROM` address (may differ from the `From:` header).", "type": "string", "example": "person@mysite.com" }, "to": { "description": "SMTP envelope `RCPT TO` address.", "type": "string", "example": "client@isp.com" }, "subject": { "nullable": true, "description": "The `Subject` header value, if available.", "type": "string", "example": "sell 0.005 shares" }, "messageId": { "nullable": true, "description": "The `Message-ID` header value, if present. Can be used with the `messageId` filter on `GET /mail/log` for subsequent lookups.", "type": "string", "example": "" }, "created": { "description": "Human-readable creation timestamp in `YYYY-MM-DD HH:MM:SS` format.", "type": "string", "example": "2021-10-14 08:50:10" }, "time": { "description": "Unix timestamp of message acceptance. Corresponds to the `startDate` and `endDate` filter parameters on `GET /mail/log`.", "type": "integer", "example": 1634215809 }, "user": { "description": "The SMTP AUTH username used to submit the message (e.g. `mb5658`). Corresponds to the `username` field in `GET /mail` orders.", "type": "string", "example": "mb5658" }, "transtype": { "description": "SMTP transaction type negotiated with the relay (e.g. `ESMTPSA`).", "type": "string", "example": "ESMTPSA" }, "origin": { "description": "IP address of the client that submitted the message to the relay. Corresponds to the `origin` filter parameter on `GET /mail/log`.", "type": "string", "example": "199.231.189.154" }, "interface": { "description": "Relay interface name that accepted the message (e.g. `feeder`).", "type": "string", "example": "feeder" }, "sendingZone": { "nullable": true, "description": "The sending zone assigned by the relay for outbound delivery.", "type": "string", "example": "interserver" }, "bodySize": { "nullable": true, "description": "Size of the message body in bytes.", "type": "integer", "example": 63 }, "seq": { "nullable": true, "description": "Sequence index of this recipient in a multi-recipient message. Starts at 1.", "type": "integer", "example": 1 }, "delivered": { "nullable": true, "description": "Delivery status flag. `1` = successfully delivered to destination MX. `0` = queued, deferred, or failed. `null` = delivery not yet attempted. Corresponds to the `delivered` filter parameter on `GET /mail/log`.", "type": "integer", "example": 1 }, "code": { "nullable": true, "description": "The SMTP response code from the destination MX server (e.g. `250` for success, `550` for permanent failure).", "type": "integer", "example": 250 }, "response": { "nullable": true, "description": "The SMTP response string received from the destination MX server upon delivery attempt (e.g. `\"250 2.0.0 Ok queued as C91D83E128C\"`).", "type": "string", "example": "250 2.0.0 Ok queued as C91D83E128C" }, "recipient": { "nullable": true, "description": "The specific recipient address this delivery record is for.", "type": "string", "example": "client@isp.com" }, "domain": { "nullable": true, "description": "The destination domain. Corresponds to the `mx` filter parameter (which matches `mxHostname`, not `domain`) on `GET /mail/log`.", "type": "string", "example": "interserver.net" }, "locked": { "nullable": true, "description": "Whether the queue entry is currently locked for delivery processing.", "type": "integer", "example": 1 }, "lockTime": { "nullable": true, "description": "Millisecond-precision timestamp of the last queue lock acquisition.", "type": "string", "example": "1634215818533" }, "assigned": { "nullable": true, "description": "The relay server node assigned to deliver this message.", "type": "string", "example": "relay1" }, "queued": { "nullable": true, "description": "ISO 8601 timestamp when the message was placed into the delivery queue.", "type": "string", "example": "2021-10-14T12:50:15.487Z" }, "mxHostname": { "nullable": true, "description": "The MX hostname the relay connected to for delivery. Corresponds to the `mx` filter parameter on `GET /mail/log`.", "type": "string", "example": "mx.j.is.cc" } }, "example": { "_id": 103172, "id": "17c7eda538e0005d03", "from": "person@mysite.com", "to": "client@isp.com", "subject": "sell 0.005 shares", "messageId": "", "created": "2021-10-14 08:50:10", "time": 1634215809, "user": "mb5658", "transtype": "ESMTPSA", "origin": "199.231.189.154", "interface": "feeder", "sendingZone": "interserver", "bodySize": 63, "seq": 1, "delivered": 1, "code": 250, "recipient": "client@isp.com", "domain": "interserver.net", "locked": 1, "lockTime": "1634215818533", "assigned": "relay1", "queued": "2021-10-14T12:50:15.487Z", "mxHostname": "mx.j.is.cc", "response": "250 2.0.0 Ok queued as C91D83E128C" } }, "MailStatsVolume": { "title": "MailStatsVolume", "description": "Top-500 breakdown of message counts within the selected time window, grouped by originating IP, destination address, and sender address.", "type": "object", "properties": { "to": { "description": "Message counts keyed by destination (envelope `to`) email address.", "type": "object", "additionalProperties": { "format": "int32", "type": "integer" } }, "from": { "description": "Message counts keyed by sender (envelope `from`) email address.", "type": "object", "additionalProperties": { "format": "int32", "type": "integer" } }, "ip": { "description": "Message counts keyed by originating client IP address.", "type": "object", "additionalProperties": { "format": "int32", "type": "integer" } } }, "example": { "to": { "client@domain.com": 395, "user@site.net": 57 }, "from": { "billing@somedomain.com": 369 }, "ip": { "1.1.1.1": 142, "2.2.2.2": 132 } } }, "MailStatsType": { "title": "MailStatsType", "description": "Account usage statistics returned by `GET /mail/stats`. Includes billing-cycle usage totals (for cost calculation) as well as time-windowed sent/received counts and volume breakdowns by IP, destination, and source address.", "type": "object", "properties": { "time": { "description": "The time window these `received`, `sent`, and `volume` statistics cover.", "default": "1h", "enum": [ "all", "billing", "month", "7d", "24h", "day", "1h" ], "x-enum-varnames": [ "All", "Billing", "Month", "SevenDays", "TwentyFourHours", "Day", "OneHour" ], "type": "string" }, "usage": { "format": "int32", "description": "Total messages accepted during the current billing cycle. Used to calculate the `cost` value.", "type": "integer" }, "currency": { "description": "The ISO 4217 currency code for this account (e.g. `USD`).", "type": "string" }, "cost": { "format": "double", "description": "Estimated cost for the current billing cycle combining the base plan price and per-email charges ($0.20/1000 emails).", "type": "number" }, "received": { "format": "int32", "description": "Count of messages accepted by the relay within the selected `time` window. Includes messages still in queue.", "type": "integer" }, "sent": { "format": "int32", "description": "Count of messages successfully delivered to the destination MX within the selected `time` window. Will be \u2264 `received`.", "type": "integer" }, "volume": { "$ref": "#/components/schemas/MailStatsVolume" } }, "example": { "time": "all", "usage": 55, "currency": "USD", "cost": 1.02, "received": 508, "sent": 495, "volume": { "to": { "client@domain.com": 395, "user@site.net": 57, "sales@company.com": 47 }, "from": { "billing@somedomain.com": 369, "sales@somedomain.com": 139 }, "ip": { "1.1.1.1": 142, "2.2.2.2": 132, "3.3.3.3": 129 } } } }, "DateOrTimestamp": { "title": "DateOrTimestamp", "description": "A date/time value accepted as either a Unix timestamp (integer seconds since epoch) or a date string parseable by `strtotime()` (e.g. `2024-01-15`, `last monday`).", "oneOf": [ { "description": "Unix timestamp (integer seconds since epoch, 0\u20139999999999).", "format": "int64", "maximum": 9999999999, "minimum": 0, "type": "integer" }, { "description": "Date string parseable by strtotime() such as `2024-01-15` or `last monday`.", "type": "string" } ] } }, "responses": { "BadInput": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "BadInputError": { "value": { "code": 400, "message": "There was a problem with the input parameters." } } } } }, "description": "Bad request \u2014 one or more input parameters were missing or invalid." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "NotFoundError": { "value": { "code": 404, "message": "The specified resource was not found." } } } } }, "description": "The specified resource was not found or does not belong to your account." }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "examples": { "UnauthorizedError": { "value": { "code": 401, "message": "API key is missing or invalid" } } } } }, "description": "Authentication failed. Ensure you are sending a valid `X-API-KEY` header. Obtain your API key from [my.interserver.net/account_security](https://my.interserver.net/account_security)." } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "description": "Pass your API key in the `X-API-KEY` HTTP request header. Obtain your key from the [Account Security](https://my.interserver.net/account_security) page on my.interserver.net.", "name": "X-API-KEY", "in": "header" } } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ { "name": "Status", "description": "Service health / uptime checks." }, { "name": "Services", "description": "View and manage your MailBaby mail service orders." }, { "name": "Sending", "description": "Send email via simple, advanced, or raw RFC 822 message submission." }, { "name": "Blocking", "description": "Manage block lists and custom deny rules to prevent unwanted outbound email." }, { "name": "History", "description": "Query sent mail logs and account usage statistics." } ], "externalDocs": { "description": "MailBaby FAQ & Tips", "url": "https://www.mail.baby/tips/" } }