> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send bulk messages with the Email API

> Sends multiple messages in one request. Paubox recommends batches of 50 or fewer. Source tracking IDs are returned in the same order as the messages array.

Each message is accepted for delivery as it is processed. If any message in the batch fails validation, the response contains only the errors, but messages that passed validation may already have been sent. Retrying the whole batch can send those messages again.




## OpenAPI

````yaml openapi1 POST /bulk_messages
openapi: 3.0.0
info:
  title: Paubox Email API
  description: >
    Public documentation for Paubox's Transactional Email API


    ## Authentication


    **IMPORTANT**: This API uses a custom authentication format that requires
    the "Token token=" prefix.


    All requests must include the Authorization header in this exact format:

    ```

    Authorization: Token token=YOUR_API_KEY

    ```


    **Note for Code Generation Tools**: Auto-generated code from this
    specification may need to be modified to include the "Token token=" prefix,
    as most generators expect standard Bearer token format.
  version: 1.0.0
servers:
  - url: https://api.paubox.com/v1/email
    description: Paubox Email API
security:
  - PauboxToken: []
tags:
  - name: Messages
    description: Send individual or bulk transactional email
  - name: Scheduled Send
    description: Schedule, check, reschedule, and cancel future email delivery
  - name: Dynamic Templates
    description: Manage and use dynamic Handlebars templates for email content
  - name: Receiving
    description: Receive inbound email — manage domains, mailboxes, and retrieve messages
  - name: Webhooks
    description: Manage webhook endpoints for delivery and inbound event notifications
paths:
  /bulk_messages:
    post:
      tags:
        - Messages
      summary: Send multiple email messages (batch)
      description: >
        Sends multiple messages in one request. Paubox recommends batches of 50
        or fewer. Source tracking IDs are returned in the same order as the
        messages array.


        Each message is accepted for delivery as it is processed. If any message
        in the batch fails validation, the response contains only the errors,
        but messages that passed validation may already have been sent. Retrying
        the whole batch can send those messages again.
      operationId: sendBulkMessages
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSendRequest'
            examples:
              twoMessages:
                summary: Two-message batch
                value:
                  data:
                    messages:
                      - recipients:
                          - recipient@host.com
                          - Recipient Name <recipient@host.com>
                        bcc:
                          - recipient3@host.com
                          - Recipient Name <recipient4@host.com>
                        headers:
                          subject: sample email
                          from: sender@authorized_domain.com
                          reply-to: Sender Name <sender@authorized_domain.com>
                          x-custom-header: sample custom header
                        content:
                          text/plain: Hello World!
                          text/html: <html><body><h1>Hello World!</h1></body></html>
                        attachments:
                          - fileName: hello_world.txt
                            contentType: text/plain
                            content: SGVsbG8gV29ybGQh
                        allowNonTLS: false
                        forceSecureNotification: false
                      - recipients:
                          - recipient2@host.com
                          - Recipient Name <recipient2@host.com>
                        headers:
                          subject: sample email
                          from: sender@authorized_domain.com
                          reply-to: Sender Name <sender@authorized_domain.com>
                        content:
                          text/plain: Hello World!
                          text/html: <html><body><h1>Hello World!</h1></body></html>
                        attachments:
                          - fileName: hello_world.txt
                            contentType: text/plain
                            content: SGVsbG8gV29ybGQh
        required: true
      responses:
        '200':
          description: Batch accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSendResponse'
              examples:
                ok:
                  value:
                    messages:
                      - sourceTrackingId: 3d38ab13-0af8-4028-bd45-999999999999
                        customHeaders:
                          X-Custom-Header: value
                        data: Service OK
                      - sourceTrackingId: 3d38ab13-0af8-4028-bd45-000000000000
                        customHeaders:
                          X-Custom-Header: value
                        data: Service OK
        '400':
          description: >-
            Bad request. A request that fails schema validation returns a single
            error object; other validation errors return an `errors` array.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/InvalidRequestResponse'
              examples:
                invalidRequest:
                  summary: Schema validation error
                  value:
                    code: 400
                    title: Invalid Request
                    details:
                      title: Missing required params
                      details: >-
                        Expected 'data.messages.0.headers.from' with String
                        type.
                      code: 400
        '401':
          description: Missing or invalid API key, or the account is not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidAccessToken:
                  value:
                    errors:
                      - code: 401
                        title: Invalid Access Token
                        details: >-
                          Access token is missing or does not match endpoint
                          username
        '403':
          description: New accounts cannot send for 24 hours after signup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                signupHold:
                  value:
                    errors:
                      - code: 403
                        title: Account Under Review
                        details: >-
                          New accounts are under review for 24 hours after
                          signup. Please try again later or contact support.
      security:
        - PauboxToken: []
components:
  schemas:
    BulkSendRequest:
      required:
        - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BulkSendRequest_data'
    BulkSendResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/BulkSendResponse_messages'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse_errors'
    InvalidRequestResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        title:
          type: string
          example: Invalid Request
        details:
          $ref: '#/components/schemas/ErrorResponse_errors'
    BulkSendRequest_data:
      required:
        - messages
      type: object
      properties:
        messages:
          type: array
          description: Recommended 50 or fewer per request.
          items:
            $ref: '#/components/schemas/Message'
    BulkSendResponse_messages:
      type: object
      properties:
        sourceTrackingId:
          type: string
        customHeaders:
          type: object
          additionalProperties:
            type: string
        data:
          type: string
          example: Service OK
    ErrorResponse_errors:
      type: object
      properties:
        code:
          type: integer
        title:
          type: string
        details:
          type: string
    Message:
      required:
        - content
        - headers
        - recipients
      type: object
      properties:
        recipients:
          minItems: 1
          type: array
          items:
            type: string
            description: >-
              Email address, optionally with display name (e.g., "J. Smith
              <jsmith@host.com>").
        bcc:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        headers:
          $ref: '#/components/schemas/MessageHeaders'
        allowNonTLS:
          type: boolean
          description: >
            Allow delivery over non-TLS rather than converting to a Secure
            Portal message. Not HIPAA compliant if the message contains PHI.
          default: false
        forceSecureNotification:
          type: boolean
          description: >
            Force delivery as a Paubox Secure Message; recipient gets a pickup
            notification with a link.
          default: false
        content:
          $ref: '#/components/schemas/MessageContent'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    MessageHeaders:
      required:
        - from
        - subject
      type: object
      properties:
        subject:
          type: string
        from:
          type: string
          description: Must match the verified domain of your API key.
        reply-to:
          type: string
          description: >-
            Reply-to address; must match a verified domain if different from
            from.
        List-Unsubscribe:
          type: string
          description: >
            Insert a List-Unsubscribe header (mailto and/or http). See RFC
            guidance for syntax.
        List-Unsubscribe-Post:
          type: string
          description: Used in conjunction with List-Unsubscribe header.
        x-custom-header:
          type: string
          description: >-
            Example custom header; any custom header may be added with an X-
            prefix.
        additionalProperties:
          type: string
          description: Any additional X- prefixed custom header values.
    MessageContent:
      type: object
      properties:
        text/plain:
          type: string
          description: Plain text message body. Required if text/html is not provided.
        text/html:
          type: string
          description: >
            HTML message body. May be HTML-escaped, base64-encoded, or a valid
            unescaped string. CSS in <style> tags will be rendered inline.
      oneOf:
        - required:
            - text/plain
        - required:
            - text/html
    Attachment:
      required:
        - content
        - contentType
        - fileName
      type: object
      properties:
        fileName:
          type: string
        contentType:
          type: string
          description: Valid MIME type, e.g., application/pdf.
        content:
          type: string
          description: Base64-encoded file contents.
        disposition:
          type: string
          description: >-
            Set to `inline` to embed the attachment in the HTML body. Inline
            attachments require `contentId` and should use an image
            `contentType`.
          enum:
            - inline
            - attachment
        contentId:
          type: string
          description: >-
            Content ID for an inline attachment. Reference it in the HTML body
            as `cid:<contentId>`.
  securitySchemes:
    PauboxToken:
      type: http
      scheme: bearer
      description: >
        Paubox API uses Bearer token authentication in the Authorization header.


        Format: `Authorization: Bearer YOUR_API_KEY_HERE`


        Example: `Authorization: Bearer
        9e5b092b632445b8f570c62ae54f30fda1044305`


        The legacy format `Authorization: Token token=YOUR_API_KEY_HERE` is also
        supported.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.