openapi.yaml

openapi: 3.0.1
info:
  title: Mailculator API
  description: API for managing email queues and sending emails.
  version: 1.0.0
paths:
  /email-queues:
    post:
      summary: Create a new email queue
      description: Receives email data and saves it to the mail queue.
      operationId: createEmailQueue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: "UUID of the message"
                      type:
                        type: string
                        enum: [email]
                        description: "The type of the resource"
                      from:
                        type: string
                        format: email
                        description: "Sender of the email"
                      reply_to:
                        type: string
                        format: email
                        description: "Reply-to address"
                      to:
                        type: string
                        format: email
                        description: "Recipient of the email"
                      subject:
                        type: string
                        description: "Subject of the email"
                      body_html:
                        type: string
                        description: "HTML body content of the email"
                      body_text:
                        type: string
                        description: "Plain text body content of the email"
                      attachments:
                        description: "Email attachments - can be array of strings (legacy) or array of objects (new format)"
                        oneOf:
                          - type: array
                            description: "Legacy format: array of file paths (filename will be extracted from path)"
                            items:
                              type: string
                              format: uri
                          - type: array
                            description: "New format: array of attachment objects with explicit path and name"
                            items:
                              type: object
                              required:
                                - path
                                - name
                              properties:
                                path:
                                  type: string
                                  format: uri
                                  description: "Path or URL to the file"
                                name:
                                  type: string
                                  description: "Original filename as it should appear in the email"
                      custom_headers:
                        type: object
                        description: "Custom headers for the email"
                        additionalProperties:
                          type: string
                      callback_on_success:
                        type: string
                        description: "Callback command (curl) to call when email is delivered to ses"
                      callback_on_failure:
                        type: string
                        description: "Callback command (curl) to call when, for some reason, email could not be delivered to ses"
      responses:
        '201':
          description: "Email queue created successfully"
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: "mail-queue"
        '400':
          description: "Invalid request body or parameters"
        '405':
          description: "Invalid HTTP method"
        '500':
          description: "Internal server error"
  /stale-emails:
    get:
      summary: Get stale emails
      description: Returns a list of all emails that are stuck in a processing state for more than the configured threshold time (default 30 minutes).
      operationId: getStaleEmails
      responses:
        '200':
          description: "List of stale emails"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StaleEmail'
        '500':
          description: "Internal server error"
  /emails/{id}/requeue:
    post:
      summary: Requeue a stale email
      description: Requeues an email by deleting the stuck status record and updating the _META record Latest field based on the current status. Only works for emails in INTAKING, PROCESSING, CALLING-SENT-CALLBACK, or CALLING-FAILED-CALLBACK states.
      operationId: requeueEmail
      parameters:
        - name: id
          in: path
          required: true
          description: "UUID of the email to requeue"
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: "Email successfully requeued"
        '400':
          description: "Invalid request (missing or invalid ID)"
        '500':
          description: "Internal server error (e.g., email not found, invalid status for requeue)"
components:
  schemas:
    Email:
      type: object
      properties:
        from:
          type: string
          format: email
        reply_to:
          type: string
          format: email
        to:
          type: string
          format: email
        subject:
          type: string
        body_html:
          type: string
        body_text:
          type: string
        attachments:
          description: "Email attachments - can be array of strings (legacy) or array of objects (new format)"
          oneOf:
            - type: array
              description: "Legacy format: array of file paths (filename will be extracted from path)"
              items:
                type: string
                format: uri
            - type: array
              description: "New format: array of attachment objects with explicit path and name"
              items:
                type: object
                required:
                  - path
                  - name
                properties:
                  path:
                    type: string
                    format: uri
                  name:
                    type: string
        custom_headers:
          type: object
          additionalProperties:
            type: string
        callback_on_success:
          type: string
        callback_on_failure:
          type: string
    StaleEmail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the email"
        status:
          type: string
          enum: [INTAKING, PROCESSING, CALLING-SENT-CALLBACK, CALLING-FAILED-CALLBACK]
          description: "Current processing status (mapped from Latest field)"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the email was created"
        updated_at:
          type: string
          format: date-time
          description: "Timestamp when the email was last updated"
      required:
        - id
        - status
        - created_at
        - updated_at