Faivelo transactional API

openapi: 3.1.0
info:
  title: Faivelo transactional API
  version: '2026-11-07'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-07: 4 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Faivelo has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 9
    documentation: 23
    pages-with-code: 2
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-07'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://faivelo.com/docs/transactional/send-api
  x-docs-section: transactional
paths:
  /api/v1/emails:
    post:
      operationId: post_api_v1_emails
      tags:
      - Api
      summary: POST /api/v1/emails
      x-source: https://faivelo.com/docs/transactional/send-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1EmailsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://faivelo.com/api/v1/emails  -H \"Authorization: Bearer $FAIVELO_API_KEY \"  -H \"Content-Type: application/json\"\
          \  -d '{\n \"from\": \"receipts@yourdomain.com\",\n \"to\": \"customer@example.com\",\n \"subject\": \"Your order is confirmed\",\n\
          \ \"html\": \"<p>Thanks for your order!</p>\"\n }'\n The from address can be any local part on any of your verified domains — no mailbox\
          \ has to exist for it. to , cc , and "
  /api/v1/emails/{id}:
    get:
      operationId: get_api_v1_emails_id
      tags:
      - Api
      summary: Poll with GET /api/v1/emails/{id}.
      description: Retrieves the current delivery status of a previously sent email.
      x-source: https://faivelo.com/docs/transactional/send-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1EmailsIdResponse'
      x-evidence:
        kind: documentation
  /api/v1/mailboxes/{address}/attachments:
    post:
      operationId: post_api_v1_mailboxes_address_attachments
      tags:
      - Api
      summary: 'upload each large file first: POST /api/v1/mailboxes/{address}/attachments.'
      description: Creates a temporary upload slot for large attachments (up to 25 MB). After receiving the response, PUT the raw file bytes to
        `upload.url` with the provided headers within 15 minutes.
      x-source: https://faivelo.com/docs/transactional/send-api
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1MailboxesAddressAttachmentsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1MailboxesAddressAttachmentsResponse'
      x-evidence:
        kind: documentation
  /api/v1/mailboxes/{address}/send:
    post:
      operationId: post_api_v1_mailboxes_address_send
      tags:
      - Api
      summary: Sending from a mailbox instead POST /api/v1/mailboxes/{address}/send sends as an existing mailbox.
      description: Sends an email as an existing mailbox. Supports both inline and previously uploaded large attachments.
      x-source: https://faivelo.com/docs/transactional/send-api
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1MailboxesAddressSendRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1MailboxesAddressSendResponse'
      x-evidence:
        kind: documentation
security:
- bearer: []
components:
  schemas:
    PostApiV1EmailsRequest:
      type: object
      properties:
        from:
          type: string
        to:
          type: string
        subject:
          type: string
        html:
          type: string
    GetApiV1EmailsIdResponse:
      type: object
      properties:
        status:
          type: string
          description: Current status of the email (sent, delivered, bounced, complained, failed).
    PostApiV1MailboxesAddressAttachmentsRequest:
      type: object
      properties:
        contentType:
          type: string
          description: MIME type of the file.
        sizeBytes:
          type: integer
          description: Size of the file in bytes (up to 25 MB).
      required:
      - contentType
      - sizeBytes
    PostApiV1MailboxesAddressAttachmentsResponse:
      type: object
      properties:
        uploadId:
          type: string
          description: Identifier to reference the uploaded file in a send request.
        upload:
          type: object
          description: Object containing `url` (PUT endpoint) and `headers` required for the raw file upload.
    PostApiV1MailboxesAddressSendRequest:
      type: object
      properties:
        from:
          type: string
          description: Sender address (must belong to the mailbox).
        to:
          type: string
          description: Recipient address(es).
        cc:
          type: string
          description: CC address(es).
        bcc:
          type: string
          description: BCC address(es).
        subject:
          type: string
          description: Email subject.
        html:
          type: string
          description: HTML body content.
        text:
          type: string
          description: Plain‑text body content.
        templateAlias:
          type: string
          description: Template alias to use.
        variables:
          type: object
          description: Template variables.
        attachments:
          type: array
          description: Attachments, each either inline (`filename`, `content`, `contentType`) or uploaded (`filename`, `contentType`, `uploadId`).
      required:
      - from
      - to
    PostApiV1MailboxesAddressSendResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the sent email.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
tags:
- name: Api