openapi: 3.1.0
info:
  title: 👨‍💻 Reusable.email API
  version: '2.0'
  description: >
    🌐 **Domain-aware by design:**  

    All API requests must be made to your assigned domain or subdomain.  

    - Example: `https://yourdomain.com/v2/` (point your domain/subdomain CNAME
    to our backend)

    - The API automatically routes & isolates data by incoming domain.


    🔒 **Authorization:**  

    Public inbox endpoints require no authentication, but private inbox
    operations must include an Inbox Token for secure access.


    💬 **Need help or have questions?**  

    Reach out anytime at [t.me/reusable](https://t.me/reusable) for direct
    support.
servers:
  - url: https://yourdomain.com
    description: Your Whitelabel Domain
security:
  - InboxToken: []
tags:
  - name: Inboxes
    description: Operations for creating, managing, and logging into inboxes.
  - name: Emails
    description: Read, list, move, and manage emails.
components:
  securitySchemes:
    InboxToken:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Format: `Inbox <token>`


        - Use the Inbox Token after logging in to a private inbox, or creating
        one.

        - This header is not required for public inboxes.
  schemas:
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      example:
        detail:
          - loc:
              - query
              - inbox_id
            msg: field required
            type: value_error.missing
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            oneOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string
    InboxCreate:
      type: object
      required:
        - inbox_address
      properties:
        inbox_address:
          type: string
          pattern: >-
            ^[a-z0-9](?:[a-z0-9._-]{0,63})@[a-z0-9](?:[a-z0-9.-]{0,253}[a-z0-9])$
          example: hello@customdomain.com
          description: Unique inbox email address (local@domain).
        is_public:
          type: boolean
          description: >
            If true, this inbox is public (anyone can access it without a
            password). If false, the inbox is private and requires a password
            for access.
          example: true
        password:
          type: string
          nullable: true
          description: Password for protected inboxes.
          example: secret123
    InboxResponse:
      type: object
      required:
        - id
        - inbox_address
      properties:
        id:
          type: string
          example: 663dbde1e0535ce2e6a1cd99
        inbox_address:
          type: string
          example: hello@customdomain.com
        is_public:
          type: boolean
          description: >
            If true, this inbox is public (anyone can access it without a
            password). If false, the inbox is private and requires a password
            for access.
          example: true
        created_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-06-01T12:00:00Z'
    InboxFolderCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: Projects
          description: Folder name (1–100 chars).
    InboxFolderResponse:
      type: object
      required:
        - id
        - inbox_id
        - name
      properties:
        id:
          type: string
          example: 663dbde1e0535ce2e6a1cdff
        inbox_id:
          type: string
          example: 663dbde1e0535ce2e6a1cd99
        name:
          type: string
          example: Sent
        unread_count:
          type: integer
          example: 0
        total_count:
          type: integer
          example: 0
        created_at:
          type: string
          nullable: true
          example: '2024-06-01T12:00:00Z'
    InboxLoginRequest:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          minLength: 1
          example: secret123
          description: Password for this inbox.
    EmailIdsPayload:
      type: object
      required:
        - email_ids
      properties:
        email_ids:
          type: array
          minItems: 1
          maxItems: 2000
          items:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          example:
            - 663dbde1e0535ce2e6a1aabb
            - 663dbde1e0535ce2e6a1aabc
    EmailFolderPayload:
      type: object
      required:
        - email_ids
        - folder_ids
      properties:
        email_ids:
          type: array
          minItems: 1
          maxItems: 2000
          items:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          example:
            - 663dbde1e0535ce2e6a1aabb
        folder_ids:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
          example:
            - 663dbde1e0535ce2e6a1bbcc
    EmailBasicResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: 663dbde1e0535ce2e6a1aabb
        subject:
          type: string
          nullable: true
          example: Welcome to Reusable.email
        sender:
          type: string
          nullable: true
          example: no-reply@somewhere.com
        recipient:
          type: string
          nullable: true
          example: user@customdomain.com
        snippet:
          type: string
          nullable: true
          example: Thanks for signing up!
        received_at:
          type: string
          nullable: true
          example: '2024-06-01T12:00:00Z'
        read_status:
          type: boolean
          example: false
        attachment_count:
          type: integer
          example: 0
    EmailContentResponse:
      type: object
      required:
        - email_id
      properties:
        email_id:
          type: string
          example: 663dbde1e0535ce2e6a1aabb
        text_body:
          type: string
          nullable: true
          example: Plain text email body here.
        html_body:
          type: string
          nullable: true
          example: <html><body>Hello!</body></html>
        raw_source:
          type: string
          nullable: true
          example: Full RFC5322 email source goes here.
        headers:
          type: object
          nullable: true
          additionalProperties:
            type: string
          example:
            Subject: Welcome
        deliverability:
          $ref: '#/components/schemas/DeliverabilityChecks'
    DeliverabilityChecks:
      type: object
      properties:
        sender_ip:
          type: string
          example: 203.0.113.1
        spf:
          $ref: '#/components/schemas/SPFData'
        dkim:
          $ref: '#/components/schemas/DKIMData'
        dmarc:
          $ref: '#/components/schemas/DMARCData'
    SPFData:
      type: object
      properties:
        passed:
          type: boolean
          example: true
        dns_record:
          type: string
          nullable: true
          example: v=spf1 include:_spf.google.com ~all
    DKIMData:
      type: object
      properties:
        passed:
          type: boolean
          example: true
        domain:
          type: string
          nullable: true
          example: somewhere.com
        selector:
          type: string
          nullable: true
          example: default
        dns_record:
          type: string
          nullable: true
    DMARCData:
      type: object
      properties:
        passed:
          type: boolean
          example: true
        dns_record:
          type: string
          nullable: true
    EmailAttachmentResponse:
      type: object
      required:
        - id
        - filename
        - content_type
        - size_bytes
      properties:
        id:
          type: string
          example: 663dbde1e0535ce2e6a1aac1
        filename:
          type: string
          example: invoice.pdf
        content_type:
          type: string
          example: application/pdf
        size_bytes:
          type: integer
          example: 35800
        s3_key:
          type: string
          nullable: true
          example: attachments/2024/06/663dbde1e0535ce2e6a1aac1
    EmailAttachmentDownloadResponse:
      type: object
      required:
        - email_id
        - attachment_id
        - filename
        - content_type
        - size_bytes
        - download_url
        - expires_in
      properties:
        email_id:
          type: string
          example: 663dbde1e0535ce2e6a1aabb
        attachment_id:
          type: string
          example: 663dbde1e0535ce2e6a1aac1
        filename:
          type: string
          example: invoice.pdf
        content_type:
          type: string
          example: application/pdf
        size_bytes:
          type: integer
          example: 35800
        download_url:
          type: string
          example: https://s3.reusable.email/download/xyz
        expires_in:
          type: integer
          example: 900
          description: Seconds until this URL expires.
    EmailFoldersResponse:
      type: object
      properties:
        email_id:
          type: string
          example: 663dbde1e0535ce2e6a1aabb
        folder_ids:
          type: array
          items:
            type: string
          example:
            - 663dbde1e0535ce2e6a1cabc
            - 663dbde1e0535ce2e6a1cabd
paths:
  /v2/inbox:
    post:
      tags:
        - Inboxes
      summary: Create inbox
      operationId: createInbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxCreate'
            examples:
              public:
                summary: Create a public inbox
                value:
                  inbox_address: john@domain.com
                  is_public: true
              private:
                summary: Create a private inbox
                value:
                  inbox_address: jane@domain.com
                  is_public: false
                  password: hunter2
      responses:
        '200':
          description: Inbox created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
              examples:
                created:
                  value:
                    id: 663dbde1e0535ce2e6a1cd99
                    inbox_address: john@domain.com
                    is_public: true
                    created_at: '2024-06-01T12:00:00Z'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              examples:
                missingAddress:
                  value:
                    detail:
                      - loc:
                          - body
                          - inbox_address
                        msg: field required
                        type: value_error.missing
                invalidEmail:
                  value:
                    detail:
                      - loc:
                          - body
                          - inbox_address
                        msg: Invalid email address format
                        type: value_error
    get:
      tags:
        - Inboxes
      summary: Get inbox by address
      operationId: getInboxByAddress
      parameters:
        - in: query
          name: inbox_address
          required: true
          schema:
            type: string
          example: hello@customdomain.com
      responses:
        '200':
          description: Inbox fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
              examples:
                ok:
                  value:
                    id: 663dbde1e0535ce2e6a1cd99
                    inbox_address: hello@customdomain.com
                    is_public: false
                    created_at: '2024-06-01T12:00:00Z'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              examples:
                missingQuery:
                  value:
                    detail:
                      - loc:
                          - query
                          - inbox_address
                        msg: field required
                        type: value_error.missing
  /v2/inbox/{inbox_id}/address:
    get:
      tags:
        - Inboxes
      summary: Get inbox address by ID
      operationId: getInboxAddressById
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
      responses:
        '200':
          description: Fetched inbox address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      inbox_address:
                        type: string
                        example: hello@customdomain.com
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  inbox_address: hello@customdomain.com
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}:
    delete:
      tags:
        - Inboxes
      summary: Delete inbox
      operationId: deleteInbox
      security:
        - InboxToken: []
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
      responses:
        '200':
          description: Inbox deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Inbox deleted successfully
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
        - Inboxes
      summary: Get inbox folders
      operationId: getInboxFolders
      security:
        - InboxToken: []
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
      responses:
        '200':
          description: List of folders in inbox.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InboxFolderResponse'
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  - id: 663dbde1e0535ce2e6a1cdff
                    inbox_id: 663dbde1e0535ce2e6a1cd99
                    name: Inbox
                    unread_count: 2
                    total_count: 7
                    created_at: '2024-06-01T12:00:00Z'
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/folder/{folder_id}:
    get:
      tags:
        - Inboxes
      summary: Get emails in folder
      operationId: getFolderEmails
      security:
        - InboxToken: []
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
        - in: path
          name: folder_id
          required: true
          schema:
            type: string
          example: 663dbde1e0535ce2e6a1cdff
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
      responses:
        '200':
          description: List emails in folder.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailBasicResponse'
                  has_more:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Emails fetched.
              example:
                success: true
                data:
                  - id: 663dbde1e0535ce2e6a1aabb
                    subject: Test message
                    sender: no-reply@domain.com
                    recipient: user@domain.com
                    snippet: This is a test
                    received_at: '2024-06-01T12:30:00Z'
                    read_status: false
                    attachment_count: 0
                has_more: false
                message: Emails fetched.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/folder:
    post:
      tags:
        - Inboxes
      summary: Create inbox folder
      operationId: createInboxFolder
      security:
        - InboxToken: []
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxFolderCreate'
      responses:
        '200':
          description: Folder created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      folder_id:
                        type: string
                        example: 663dbde1e0535ce2e6a1cdef
                  message:
                    type: string
                    example: Folder created.
              example:
                success: true
                data:
                  folder_id: 663dbde1e0535ce2e6a1cdef
                message: Folder created.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - Inboxes
      summary: Delete inbox folder
      operationId: deleteInboxFolder
      security:
        - InboxToken: []
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
        - in: query
          name: folder_id
          required: true
          schema:
            type: string
            example: 663dbde1e0535ce2e6a1cdef
      responses:
        '200':
          description: Folder deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Folder deleted.
              example:
                success: true
                message: Folder deleted.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/login:
    post:
      tags:
        - Inboxes
      summary: Login to a private inbox by ID
      operationId: inboxLogin
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
          example: 663dbde1e0535ce2e6a1cd99
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxLoginRequest'
      responses:
        '200':
          description: Logged in to inbox.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  inbox_token:
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  message:
                    type: string
                    example: Inbox login successful.
              example:
                success: true
                inbox_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                message: Inbox login successful.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/fetch-id:
    get:
      tags:
        - Inboxes
      summary: Get inbox ID by address
      operationId: fetchInboxIdByAddress
      parameters:
        - in: query
          name: inbox_address
          required: true
          schema:
            type: string
            example: hello@customdomain.com
      responses:
        '200':
          description: Inbox ID fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      inbox_id:
                        type: string
                        example: 663dbde1e0535ce2e6a1cd99
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  inbox_id: 663dbde1e0535ce2e6a1cd99
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}:
    get:
      tags:
        - Emails
      summary: Fetch email (basic)
      operationId: fetchEmailBasic
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/EmailBasicResponse'
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  id: 663dbde1e0535ce2e6a1aabb
                  subject: Welcome to Reusable.email
                  sender: no-reply@somewhere.com
                  recipient: user@customdomain.com
                  snippet: Thanks for signing up!
                  received_at: '2024-06-01T12:00:00Z'
                  read_status: false
                  attachment_count: 0
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
        - Emails
      summary: Delete email (single)
      operationId: deleteEmail
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Email deleted successfully
              example:
                success: true
                message: Email deleted successfully
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/attachments:
    get:
      tags:
        - Emails
      summary: Fetch email attachments
      operationId: fetchEmailAttachments
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email attachments listed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      attachments:
                        type: array
                        items:
                          $ref: '#/components/schemas/EmailAttachmentResponse'
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  attachments:
                    - id: 663dbde1e0535ce2e6a1aac1
                      filename: invoice.pdf
                      content_type: application/pdf
                      size_bytes: 35800
                      s3_key: attachments/2024/06/663dbde1e0535ce2e6a1aac1
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/attachment/{attachment_id}:
    get:
      tags:
        - Emails
      summary: Download email attachment
      description: Generates a presigned S3 URL to download the specified attachment.
      operationId: downloadEmailAttachment
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: attachment_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Presigned download URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/EmailAttachmentDownloadResponse'
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  email_id: 663dbde1e0535ce2e6a1aabb
                  attachment_id: 663dbde1e0535ce2e6a1aac1
                  filename: invoice.pdf
                  content_type: application/pdf
                  size_bytes: 35800
                  download_url: https://s3.reusable.email/abcxyz
                  expires_in: 900
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/html:
    get:
      tags:
        - Emails
      summary: Fetch email HTML
      operationId: fetchEmailHtml
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email HTML fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      html_body:
                        type: string
                        nullable: true
                        example: <html><body>Hello!</body></html>
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  html_body: <html><body>Hello!</body></html>
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/text:
    get:
      tags:
        - Emails
      summary: Fetch email text
      operationId: fetchEmailText
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email text body fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      text_body:
                        type: string
                        nullable: true
                        example: Plain text email body here.
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  text_body: Plain text email body here.
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/raw:
    get:
      tags:
        - Emails
      summary: Fetch email raw
      operationId: fetchEmailRaw
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Raw email source fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      raw_source:
                        type: string
                        nullable: true
                        example: Full RFC5322 email source goes here.
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  raw_source: Full RFC5322 email source goes here.
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/headers:
    get:
      tags:
        - Emails
      summary: Fetch email headers
      operationId: fetchEmailHeaders
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email headers fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      headers:
                        type: object
                        additionalProperties:
                          type: string
                        example:
                          Subject: Welcome
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  headers:
                    Subject: Welcome
                    From: no-reply@somewhere.com
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/deliverability:
    get:
      tags:
        - Emails
      summary: Fetch email deliverability
      operationId: fetchEmailDeliverability
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email deliverability details fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      deliverability:
                        $ref: '#/components/schemas/DeliverabilityChecks'
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  deliverability:
                    sender_ip: 203.0.113.1
                    spf:
                      passed: true
                      dns_record: v=spf1 include:_spf.google.com ~all
                    dkim:
                      passed: true
                      domain: somewhere.com
                      selector: default
                      dns_record: v=DKIM1; k=rsa; p=...
                    dmarc:
                      passed: true
                      dns_record: v=DMARC1; p=none; rua=mailto:postmaster@domain.com
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/{email_id}/folder:
    get:
      tags:
        - Emails
      summary: Get email folders
      operationId: getEmailFolders
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
        - in: path
          name: email_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      responses:
        '200':
          description: Email folder IDs fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      folder_ids:
                        type: array
                        items:
                          type: string
                        example:
                          - 663dbde1e0535ce2e6a1cabc
                          - 663dbde1e0535ce2e6a1cabd
                  message:
                    type: string
                    nullable: true
              example:
                success: true
                data:
                  folder_ids:
                    - 663dbde1e0535ce2e6a1cabc
                message: null
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/read:
    post:
      tags:
        - Emails
      summary: Bulk mark emails as read
      operationId: bulkMarkRead
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailIdsPayload'
            example:
              email_ids:
                - 663dbde1e0535ce2e6a1aabb
                - 663dbde1e0535ce2e6a1aabc
      responses:
        '200':
          description: Emails marked as read.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Marked 2 emails as read.
                  updated_count:
                    type: integer
                    example: 2
              example:
                success: true
                message: Marked 2 emails as read.
                updated_count: 2
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/unread:
    post:
      tags:
        - Emails
      summary: Bulk mark emails as unread
      operationId: bulkMarkUnread
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailIdsPayload'
            example:
              email_ids:
                - 663dbde1e0535ce2e6a1aabb
                - 663dbde1e0535ce2e6a1aabc
      responses:
        '200':
          description: Emails marked as unread.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Marked 2 emails as unread.
                  updated_count:
                    type: integer
                    example: 2
              example:
                success: true
                message: Marked 2 emails as unread.
                updated_count: 2
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email/folder:
    post:
      tags:
        - Emails
      summary: Bulk move emails to folders
      operationId: bulkMoveEmailsToFolder
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailFolderPayload'
            example:
              email_ids:
                - 663dbde1e0535ce2e6a1aabb
              folder_ids:
                - 663dbde1e0535ce2e6a1bbcc
      responses:
        '200':
          description: Emails assigned to folders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Assigned 1 folder references.
                  updated_count:
                    type: integer
                    example: 1
              example:
                success: true
                message: Assigned 1 folder references.
                updated_count: 1
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/inbox/{inbox_id}/email:
    delete:
      tags:
        - Emails
      summary: Bulk delete emails
      operationId: bulkDeleteEmails
      parameters:
        - in: path
          name: inbox_id
          required: true
          schema:
            type: string
            minLength: 24
            maxLength: 24
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailIdsPayload'
            example:
              email_ids:
                - 663dbde1e0535ce2e6a1aabb
                - 663dbde1e0535ce2e6a1aabc
      responses:
        '200':
          description: Emails deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Deleted 2 emails.
                  deleted_count:
                    type: integer
                    example: 2
              example:
                success: true
                message: Deleted 2 emails.
                deleted_count: 2
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
