openapi: 3.0.3
info:
    title: postal
    description: The Postal Service is the service that mails letters on behalf of other services. It abstracts away the underlying mail provider, ensuring consistent and reliable delivery.
    version: 1.0.0
servers:
    - url: https://postal.platform.arb.inc
paths:
    /:
        get:
            summary: Get basic service information
            description: Returns a plain text welcome message with the service name and creation date.
            operationId: getRoot
            responses:
                '200':
                    description: Successfully retrieved welcome message.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Welcome to the postal service. Created on September 22, 2025 by Al Beebe
            tags:
                - /
    /mailings/create:
        post:
            summary: Create a mailing
            description: Upload an address and PDF to create a mailing. Send the JSON parameters first, then the PDF. The whole request must be under 10 MiB.
            operationId: createMailing
            requestBody:
                required: true
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            required:
                                - parameters
                                - pdf
                            properties:
                                parameters:
                                    type: string
                                    description: JSON string with mailing details. This field must be the first part in the multipart body.
                                    example: |
                                        {
                                          "mailType": "pressureSealed",
                                          "idempotencyKey": "6b2cf4b8-40e9-4f2a-9f15-2d1e8b0d9b4e",
                                          "recipient": {
                                            "name": "Jane Doe",
                                            "address": "123 Main St Apt 4B",
                                            "city": "Springfield",
                                            "state": "IL",
                                            "zipcode": "62704"
                                          }
                                        }
                                pdf:
                                    type: string
                                    format: binary
                                    description: PDF file to mail. Must be content-type application/pdf.
                                    example: document.pdf
                        encoding:
                            parameters:
                                contentType: text/plain; charset=utf-8
                            pdf:
                                contentType: application/pdf
            responses:
                '200':
                    description: Mailing queued successfully.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    id:
                                        type: string
                                        description: ID of the created mailing.
                                        example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
                '409':
                    description: A mailing with the same idempotency key already exists.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Mailing already exists
                '410':
                    description: The uploaded PDF is too large.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: PDF is too large
            tags:
                - mailings
components:
    securitySchemes:
        bearerAuth:
            type: http
            description: access token
            scheme: bearer
            bearerFormat: JWT
tags:
    - name: /
    - name: mailings