openapi: 3.1.0
info:
  title: Maileroo Email Emails API
  description: The Maileroo REST API allows sending transactional and marketing emails via JSON requests with high deliverability. Supports HTML and plain text emails, attachments, tracking, templates, scheduled delivery, and bulk sending. All requests are authenticated via an API sending key passed in the X-Api-Key header or as a Bearer token in the Authorization header.
  version: '2.0'
  contact:
    name: Maileroo Support
    url: https://maileroo.com/docs/
  termsOfService: https://maileroo.com/terms
servers:
- url: https://smtp.maileroo.com/api/v2
  description: Production
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Emails
  description: Send transactional and bulk emails
paths:
  /emails:
    post:
      operationId: sendBasicEmail
      summary: Send a basic email
      description: Send a transactional email with HTML and/or plain text content. Supports attachments, tracking, custom tags and headers, and scheduled delivery via RFC 3339 timestamps or natural language.
      tags:
      - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasicEmailRequest'
      responses:
        '200':
          description: Email accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /emails/template:
    post:
      operationId: sendTemplatedEmail
      summary: Send a templated email
      description: Send an email using a template defined in the Maileroo dashboard. Template variables are merged via the template_data object.
      tags:
      - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplatedEmailRequest'
      responses:
        '200':
          description: Email accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Validation error
        '401':
          description: Authentication failed
  /emails/bulk:
    post:
      operationId: sendBulkEmails
      summary: Send bulk emails
      description: Send up to 500 emails in a single request, each with its own recipient and merge variables. Common subject and body content applies across messages, with per-message overrides.
      tags:
      - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEmailRequest'
      responses:
        '200':
          description: Emails accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSendResponse'
        '400':
          description: Validation error
        '401':
          description: Authentication failed
components:
  schemas:
    SendResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
          properties:
            reference_id:
              type: string
    BulkMessage:
      type: object
      required:
      - from
      - to
      properties:
        from:
          $ref: '#/components/schemas/EmailObject'
        to:
          $ref: '#/components/schemas/EmailObject'
        template_data:
          type: object
        reference_id:
          type: string
    BasicEmailRequest:
      type: object
      required:
      - from
      - to
      - subject
      properties:
        from:
          $ref: '#/components/schemas/EmailObject'
        to:
          oneOf:
          - $ref: '#/components/schemas/EmailObject'
          - type: array
            items:
              $ref: '#/components/schemas/EmailObject'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailObject'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailObject'
        reply_to:
          type: array
          items:
            $ref: '#/components/schemas/EmailObject'
        subject:
          type: string
          maxLength: 255
        html:
          type: string
        plain:
          type: string
        tracking:
          type: boolean
        tags:
          type: object
          additionalProperties:
            type: string
        headers:
          type: object
          additionalProperties:
            type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        scheduled_at:
          type: string
          description: RFC 3339 timestamp or natural language schedule
        reference_id:
          type: string
          description: 24-character hex ID; auto-generated if omitted
    Attachment:
      type: object
      required:
      - file_name
      - content
      properties:
        file_name:
          type: string
        content:
          type: string
          description: Base64-encoded file content
        content_type:
          type: string
        inline:
          type: boolean
        content_id:
          type: string
    EmailObject:
      type: object
      required:
      - address
      properties:
        address:
          type: string
          format: email
        display_name:
          type: string
    BulkEmailRequest:
      type: object
      required:
      - subject
      - messages
      properties:
        subject:
          type: string
          maxLength: 255
        messages:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/BulkMessage'
        template_id:
          type: integer
        html:
          type: string
        plain:
          type: string
        tracking:
          type: boolean
        tags:
          type: object
        headers:
          type: object
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    TemplatedEmailRequest:
      allOf:
      - $ref: '#/components/schemas/BasicEmailRequest'
      - type: object
        required:
        - template_id
        properties:
          template_id:
            type: integer
          template_data:
            type: object
            additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          nullable: true
    BulkSendResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
          properties:
            reference_ids:
              type: array
              items:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
    BearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Maileroo Email API Documentation
  url: https://maileroo.com/docs/email-api/introduction/