openapi: 3.0.3
info:
    title: emails
    description: The Emails Service is responsible for sending emails on behalf of other services. It also manages and stores all email templates to ensure consistent and centralized communication formatting.
    version: 1.0.0
servers:
    - url: https://emails.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 emails service. Created on July 31, 2025 by Al Beebe
            tags:
                - /
    /emails/send:
        post:
            summary: Send an email
            description: Sends an email using a provided HTML body or a stored template. Requires valid email addresses, a future expiration timestamp, and proper subject/content format.
            operationId: sendEmail
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - expires
                                - from
                                - to
                                - replyTo
                                - subject
                            properties:
                                expires:
                                    type: string
                                    format: date-time
                                    description: Expiration time for the email. Must be in the future and within 7 days.
                                    example: "2025-08-11T15:04:05Z"
                                from:
                                    type: object
                                    required:
                                        - address
                                    properties:
                                        name:
                                            type: string
                                            description: Display name for the sender.
                                            example: Alice Smith
                                        address:
                                            type: string
                                            description: Sender's email address.
                                            example: alice@example.com
                                to:
                                    type: array
                                    minItems: 1
                                    items:
                                        type: object
                                        required:
                                            - address
                                        properties:
                                            name:
                                                type: string
                                                description: Display name for the recipient.
                                                example: Bob Lee
                                            address:
                                                type: string
                                                description: Recipient's email address.
                                                example: bob@example.com
                                cc:
                                    type: array
                                    items:
                                        type: object
                                        required:
                                            - address
                                        properties:
                                            name:
                                                type: string
                                                description: Display name for the CC recipient.
                                                example: Carol Doe
                                            address:
                                                type: string
                                                description: CC recipient's email address.
                                                example: carol@example.com
                                bcc:
                                    type: array
                                    items:
                                        type: object
                                        required:
                                            - address
                                        properties:
                                            name:
                                                type: string
                                                description: Display name for the BCC recipient.
                                                example: Dan Roe
                                            address:
                                                type: string
                                                description: BCC recipient's email address.
                                                example: dan@example.com
                                replyTo:
                                    type: object
                                    required:
                                        - address
                                    properties:
                                        name:
                                            type: string
                                            description: Display name for the reply-to address.
                                            example: Support Team
                                        address:
                                            type: string
                                            description: Reply-to email address.
                                            example: support@example.com
                                subject:
                                    type: string
                                    maxLength: 100
                                    description: Subject of the email.
                                    example: Welcome to our service!
                                template:
                                    type: object
                                    properties:
                                        name:
                                            type: string
                                            description: Name of the stored template.
                                            example: welcome-template
                                        substitutions:
                                            type: object
                                            additionalProperties:
                                                type: string
                                            description: Key-value pairs for template substitution.
                                            example:
                                                firstName: Alice
                                                plan: Premium
                                html:
                                    type: string
                                    description: Raw HTML content of the email (used if template is not provided).
                                    example: "<p>Hello, welcome to our service!</p>"
                                text:
                                    type: string
                                    description: Optional plain text version of the email.
                                    example: "Hello, welcome to our service!"
            responses:
                '200':
                    description: Email successfully queued for sending.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    id:
                                        type: string
                                        description: Unique identifier of the queued email.
                                        example: "c30860df-19b7-47f3-bf46-b6a08e9c249a"
                '409':
                    description: Email conflict, such as specifying both template and HTML.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Specify either 'template' or 'html', not both
            tags:
                - emails
    /templates/create:
        post:
            summary: Create a new template
            description: Creates a new HTML template. Template names must follow naming rules and be unique.
            operationId: createTemplate
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - name
                                - html
                            properties:
                                name:
                                    type: string
                                    description: Template name. Must be lowercase and contain only letters, numbers, dashes (-), underscores (_), and periods (.).
                                    example: invoice-template.v1
                                html:
                                    type: string
                                    description: HTML content of the template. Must be between 1 and 100,000 characters.
                                    example: "<html><body><h1>Invoice</h1></body></html>"
            responses:
                '200':
                    description: Template successfully created.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: template successfully created
                '409':
                    description: A template with that name already exists.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: A template already exists with that name
            tags:
                - templates
    /templates/update:
        post:
            summary: Update an existing HTML template
            description: Updates the HTML content of an existing template identified by its name. The name must already exist in the system.
            operationId: updateTemplate
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - name
                                - html
                            properties:
                                name:
                                    type: string
                                    description: Name of the template to update. Must be 1–50 characters and can only contain lowercase letters (a–z), numbers (0–9), dashes (-), underscores (_), and periods (.).
                                    example: welcome-email
                                html:
                                    type: string
                                    description: New HTML content for the template. Must be between 1 and 100,000 characters.
                                    example: "<html><body><h1>Welcome!</h1></body></html>"
            responses:
                '200':
                    description: Template successfully updated.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: template successfully update
                '404':
                    description: Template not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: a template with that name does not exist
            tags:
                - templates
components:
    securitySchemes:
        bearerAuth:
            type: http
            description: access token
            scheme: bearer
            bearerFormat: JWT
tags:
    - name: /
    - name: emails
    - name: templates