openapi: 3.1.0
info:
  title: Mailtrap Email Sending Inboxes Send API
  description: The Mailtrap Email Sending API allows sending transactional and bulk emails with high deliverability. It follows REST principles and supports authentication via API tokens, with all requests sent over HTTPS. The API exposes a JSON-based send endpoint and a batch endpoint capable of delivering up to 500 emails in a single request.
  version: '1.0'
  contact:
    name: Mailtrap Support
    url: https://help.mailtrap.io/
  termsOfService: https://mailtrap.io/terms-of-use/
servers:
- url: https://send.api.mailtrap.io
  description: Transactional email production
- url: https://bulk.api.mailtrap.io
  description: Bulk stream production
security:
- BearerAuth: []
tags:
- name: Send
  description: Send transactional and bulk emails
paths:
  /api/send:
    post:
      operationId: sendEmail
      summary: Send a transactional email
      description: Send a single transactional email in real time. Supports HTML and text bodies, attachments, headers, custom variables, and category tagging.
      tags:
      - Send
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendRequest'
      responses:
        '200':
          description: Email accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Validation error
        '401':
          description: Authentication failed
        '403':
          description: Quota or permission error
  /api/batch:
    post:
      operationId: sendBatchEmails
      summary: Send batch emails
      description: Send up to 500 emails in a single request. A base message defines shared fields and per-recipient requests override or supplement them.
      tags:
      - Send
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Validation error
        '401':
          description: Authentication failed
  /api/send/{inbox_id}:
    post:
      operationId: sendToSandboxInbox
      summary: Send a test email to a sandbox inbox
      description: Send an email into a specific sandbox inbox for inspection and debugging. Uses the same JSON body shape as the production send API.
      tags:
      - Send
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendRequest_2'
      responses:
        '200':
          description: Email captured by the sandbox inbox
        '401':
          description: Authentication failed
components:
  schemas:
    SendResponse:
      type: object
      properties:
        success:
          type: boolean
        message_ids:
          type: array
          items:
            type: string
    BatchResponse:
      type: object
      properties:
        success:
          type: boolean
        responses:
          type: array
          items:
            $ref: '#/components/schemas/SendResponse'
    Attachment:
      type: object
      required:
      - content
      - filename
      properties:
        content:
          type: string
          description: Base64-encoded file content
        filename:
          type: string
        type:
          type: string
        disposition:
          type: string
          enum:
          - attachment
          - inline
        content_id:
          type: string
    BatchRequest:
      type: object
      required:
      - base
      - requests
      properties:
        base:
          $ref: '#/components/schemas/SendRequest'
        requests:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/BatchMessage'
    Address:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        name:
          type: string
    SendRequest:
      type: object
      required:
      - from
      - to
      - subject
      properties:
        from:
          $ref: '#/components/schemas/Address'
        to:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        reply_to:
          $ref: '#/components/schemas/Address'
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        category:
          type: string
        custom_variables:
          type: object
          additionalProperties:
            type: string
        headers:
          type: object
          additionalProperties:
            type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        template_uuid:
          type: string
        template_variables:
          type: object
          additionalProperties: true
    SendRequest_2:
      type: object
      required:
      - from
      - to
      - subject
      properties:
        from:
          $ref: '#/components/schemas/Address'
        to:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        subject:
          type: string
        text:
          type: string
        html:
          type: string
    BatchMessage:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/Address'
        to:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        custom_variables:
          type: object
        template_variables:
          type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Mailtrap Email API Documentation
  url: https://docs.mailtrap.io/