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.**


        # Overview


        This 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).


        # Mail Orders


        Every sending account in MailBaby is backed by a **Mail Order** — a provisioned sending credential
        with a numeric `id` and a corresponding SMTP username (`mb<id>`).  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.


        # Sending Email


        Three sending methods are available depending on your use-case:

        | 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) |


        After 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.


        # Filtering & Logs


        `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 — e.g. `from`, `to`, `subject`, `messageId`,
        `origin`, `mx`, `startDate`/`endDate`, and `delivered`.


        # Blocking


        Two independent mechanisms exist for suppressing unwanted email:

        - **Block lists** (`GET /mail/blocks`, `POST /mail/blocks/delete`) — addresses flagged by the
          system spam filters (LOCAL_BL_RCPT / MBTRAP rules in rspamd, and suspicious subjects).
        - **Deny rules** (`GET /mail/rules`, `POST /mail/rules`, `DELETE /mail/rules/{ruleId}`) —
          custom rules you configure to reject specific senders, domains, destination addresses, or
          subject-line prefixes before a message is even attempted.


        # Authentication


        In order to use most of the API calls you must pass credentials from the
        [my.interserver.net](https://my.interserver.net/) site.

        We 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.

        Pass your key in the `X-API-KEY` HTTP request header for every protected call.
    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 — 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.
            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<id>`), and an optional
                `comment`.


                The `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.


                To retrieve full details — including the current SMTP password — for a single order use `GET
                /mail/{id}`.
    '/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`.


                The `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.


                The `id` path parameter is the same integer `id` value returned by `GET /mail`.
    /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** — 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.


                **HTML detection** is automatic — if the `body` value contains any HTML tags the message will
                be sent as `text/html`; otherwise it is sent as `text/plain`.


                The `from` address is also automatically set as the `Reply-To` header.


                *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`.


                On 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.
    /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.


                This endpoint is particularly useful when the message has already been **DKIM-signed** —
                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.


                The `From` and recipient addresses are parsed automatically from the message headers (`From`,
                `To`, `Cc`, `Bcc`).  You do **not** need to specify them separately.


                If 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.


                On 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.
    /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 <user@domain.com>
                                    to: Jane <support@interserver.net>
                            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 <user@domain.com>
                                    to: Joe <support@interserver.net>
                            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** — 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.


                **Content-type flexibility** — 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 <joe@example.com>, jane@example.com"`) and the structured
                `[{"email":"...","name":"..."}]` array format.  When using JSON, both formats are equally
                supported.


                **HTML detection** is automatic — if `body` contains HTML tags the `Content-Type` is set to
                `text/html`; otherwise `text/plain`.


                **Attachments** must be base64-encoded.  Each attachment requires at least a `data` field; the
                optional `filename` field controls the attachment name shown to recipients.


                If an `id` is provided it must correspond to an active mail order on your account. If omitted,
                the first active order is selected automatically.


                On success the response `text` field contains the relay transaction ID which can be looked up
                in `GET /mail/log` via the `mailid` query parameter.


                ## Examples


                ### Form — basic string addresses

                ```sh curl -X POST https://api.mailbaby.net/mail/advsend \
                  -H 'X-API-KEY: YOUR_API_KEY' \
                  -H 'Content-Type: application/x-www-form-urlencoded' \
                  -d 'subject=Welcome' \
                  -d 'body=Hello' \
                  -d from=user@domain.com \
                  -d to=support@interserver.net
                ```

                ### Form — RFC 822 named addresses

                ```sh curl -X POST https://api.mailbaby.net/mail/advsend \
                  -H 'X-API-KEY: YOUR_API_KEY' \
                  -H 'Content-Type: application/x-www-form-urlencoded' \
                  -d 'subject=Welcome' \
                  -d 'body=Hello' \
                  -d 'from=Joe <user@domain.com>' \
                  -d 'to=Jane <support@interserver.net>'
                ```

                ### Form — multiple recipients as array

                ```sh curl -X POST https://api.mailbaby.net/mail/advsend \
                  -H 'X-API-KEY: YOUR_API_KEY' \
                  -H 'Content-Type: application/x-www-form-urlencoded' \
                  -d 'subject=Welcome' -d 'body=Hello' \
                  -d from=user@domain.com \
                  -d 'to[0][name]=Joe' -d 'to[0][email]=support@interserver.net' \
                  -d 'to[1][name]=Jane' -d 'to[1][email]=jane@interserver.net'
                ```

                ### JSON — structured objects

                ```sh curl -X POST https://api.mailbaby.net/mail/advsend \
                  -H 'X-API-KEY: YOUR_API_KEY' \
                  -H 'Content-Type: application/json' \
                  -d '{
                    "subject": "Welcome",
                    "body": "<h1>Hello</h1>",
                    "from": {"email": "user@domain.com", "name": "Sender Name"},
                    "to": [{"email": "joe@client.com", "name": "Joe Client"}],
                    "cc": [{"email": "manager@client.com"}],
                    "attachments": [{"filename": "report.pdf", "data": "BASE64_DATA"}]
                  }'
                ```
    /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–19 character hexadecimal string such as
                        `185997065c60008840`.
                    schema:
                        maxLength: 19
                        minLength: 18
                        type: string
                    in: query
                    required: false
                -
                    example: <abc123@yourdomain.com>
                    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 — 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: >-
                                                    <vmiLEebsuCbSpUxD7oN3REpaN4VbN6BrdCAbNKIrdAo@relay0.mailbaby.net>
                                                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: >-
                                                    <vmiLEebsuCbSpUxD7oN3REpaN4VbN6BrdCAbNKIrdAo@relay0.mailbaby.net>
                                                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).


                **Row grouping** is controlled by the `groupby` parameter.  By default (`groupby=recipient`),
                the response contains one row per delivery attempt — 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).


                **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.


                **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`.


                **Sorting** is controlled by `sort` and `dir`.  Currently the only sort key is `time`
                (default), which orders by internal row ID.


                **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.


                **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.


                The `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`.


                The `messageId` parameter searches the `Message-ID` email header (case-insensitive substring
                match).
    /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`.


                The response includes:

                - **`usage`** — total messages accepted by the relay during the current billing
                  cycle (used for cost calculation).
                - **`cost`** — estimated cost for the billing cycle based on the base plan price
                  plus per-email charges.
                - **`received`** / **`sent`** — count of messages accepted by the relay /
                  successfully delivered to the destination MX within the selected `time` window.
                - **`volume`** — top-500 breakdown of message counts grouped by source IP (`ip`),
                  destination address (`to`), and sender address (`from`) within the selected window.


                **Time windows** (controlled by the `time` parameter):

                | 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 |
    /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:


                - **`local`** — messages flagged by the `LOCAL_BL_RCPT` rspamd rule.  These are
                  messages sent to recipients on your account's local block list.
                - **`mbtrap`** — messages flagged by the `MBTRAP` rspamd rule.  These are messages
                  that triggered MailBaby's internal trap / honeypot detection.
                - **`subject`** — senders whose recent messages contain spam-indicative subjects
                  (strings containing `@`, `smtp`, `socks4`, or `socks5`) with high repetition
                  (more than 4 identical subjects from the same sender in the last 3 days).


                The `local` and `mbtrap` results cover the last 5 days.  The `subject` results cover the last
                3 days.


                A sender address returned in any of these lists can be delisted using `POST
                /mail/blocks/delete` with the `email` field set to that address.
    /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 — 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:

                1. The rspamd spam-filter database (`fromemail` / envelope sender records). 2. The
                MailChannels integration block table. 3. The MailBaby internal block table.


                Use `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.


                **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.
    /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.


                Four rule types are supported:

                | `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) |


                Use `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.
        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.


                The `type` field selects the matching strategy:

                - **`email`** — exact match against the SMTP envelope `MAIL FROM` address. - **`domain`** —
                matches any sender address at the specified domain. - **`destination`** — exact match against
                the SMTP envelope `RCPT TO` address. - **`startswith`** — matches any sender address whose
                local-part (the portion
                  before the `@`) starts with the given string.  Only alphanumeric characters
                  and `+`, `_`, `.`, `-` are permitted in the prefix.


                If `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.


                On 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.
    '/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 — 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`.


                The `ruleId` is the `id` field returned by `GET /mail/rules` or the `text` field from a
                successful `POST /mail/rules` response.


                Only rules belonging to your own active mail account(s) can be deleted — the server will
                reject attempts to delete rules that belong to a different account.
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
                — 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<id>` 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<id>`. 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 <joe@example.com>, jane@example.com"`.
                    type: string
                    example: Joe <joe@example.com>
                -
                    $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 <email>"` 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 <user@domain.com>"`.
                    type: string
                    example: Joe <user@domain.com>
                -
                    $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 <email>"`), 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 — 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.


                For 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.


                Address fields (`from`, `to`, `replyto`, `cc`, `bcc`) each accept either a plain RFC 822
                string (e.g. `"Joe <joe@example.com>"` or a comma-separated list) or a structured array of
                `{"email": "...", "name": "..."}` objects.


                HTML 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
                        <email>"`), 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.


                The `From`, `To`, `Cc`, and `Bcc` addresses are extracted from the message headers
                automatically — 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
                    To: Me <support@interserver.net>
                    From: Mail Test <support@interserver.net>
                    Reply-To: Mail Test <support@interserver.net>
                    Subject: testing out raw email api call
                    Message-ID: <9jeLkYQIw7KqYnoiCnnYj7EC0IrSHdp8XMuJq9a5qs@interserver.net>
                    MIME-Version: 1.0
                    Content-Type: text/plain; charset=utf-8
                    DKIM-Signature: v=1; d=interserver.net; s=my; a=rsa-sha256; ...

                    This is a test of the rawsend API call.
        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:

                - `email` — exact sender address match - `domain` — all senders from a domain - `destination`
                — exact recipient address match - `startswith` — 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).


                Key field relationships with other API calls:

                - The `id` field matches the `mailid` query parameter on `GET /mail/log` and
                  the `text` field of a successful send response.
                - The `from` address can be passed to `POST /mail/blocks/delete` to delist a
                  flagged sender.
                - The `user` field is the SMTP username (e.g. `mb5658`) corresponding to the
                  `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–19 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: <vmiLEebsuCbSpUxD7oN3REpaN4VbN6BrdCAbNKIrdAo@relay0.mailbaby.net>
                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: <vmiLEebsuCbSpUxD7oN3REpaN4VbN6BrdCAbNKIrdAo@relay0.mailbaby.net>
                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 ≤ `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–9999999999).
                    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 — 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/'
