> ## Documentation Index
> Fetch the complete documentation index at: https://empirical.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an email

> Sends an email from an @empiricalrun.email address, with optional attachments. Each recipient must be an @empiricalrun.email address, someone who emailed the sender (with DMARC passing), or one of the project's allowed recipients (see Allowed recipients). Use it to test apps that receive email (reply-by-email, email-to-ticket, forwarding). Replies arrive in the sender's inbox; read them with `listAddressMessages`. Limits: 5 recipients and 5 attachments (5 MiB in total) per email; 10 emails per minute and 100 per rolling 24 hours per project. Emails whose recipients are all @empiricalrun.email addresses have separate, higher limits: 60 per minute and 1000 per rolling 24 hours. Over a limit the request fails with 429.



## OpenAPI

````yaml /api-reference/openapi.generated.json post /api/inboxes/send
openapi: 3.1.0
info:
  title: Empirical API
  version: 1.0.0
  description: Programmatic access to Empirical test runs, snoozes, and more.
  contact:
    name: Empirical
    url: https://empirical.run
servers:
  - url: https://api.empirical.run
security:
  - Bearer: []
tags:
  - name: Test Runs
    description: Trigger, list, and inspect end-to-end test runs.
  - name: Test Cases
    description: >-
      Browse the Playwright test cases synced from a project's repository and
      manage their tags.
  - name: Environments
    description: >-
      Named deployment targets (slug + Playwright project filters) a project's
      tests run against.
  - name: Snoozes
    description: Temporarily suppress known test failures for specific Playwright tests.
  - name: KV
    description: >-
      Project-scoped key-value store shared by test runs, shards and agent
      sessions. Every entry expires; conditional writes make it safe for locks.
  - name: Analytics
    description: Aggregated test-run, test-count and test-case analytics for a project.
  - name: Allowed recipients
    description: >-
      Domains and addresses a project's inboxes may send email to, besides
      @empiricalrun.email addresses and people who emailed the inbox. Each one
      is verified in one of two ways. **Email from it**: send an email from the
      domain (any mailbox on it) or from the exact address to the verification
      address, with the verification code in the subject. It must pass DMARC.
      **Emailed code**, for addresses that can't send (e.g.
      `support@acme.zendesk.com`): we email the address a 6-digit code, and you
      enter it from wherever that address delivers. A domain covers exactly that
      domain, not its subdomains; add a subdomain such as `inbound.acme.com` on
      its own, and an email from `@acme.com` verifies it. Public mail providers
      (gmail.com, outlook.com and similar) can't be added as domains; add the
      exact address instead. An address also covers its plus-variants. Domains
      reserved for examples and tests (example.com, example.net, example.org,
      and anything under .test, .example, .invalid or .localhost) can't receive
      email, so codes are never emailed to them.
  - name: Badges
    description: Public README status badge images (SVG) for project environments.
  - name: Files
    description: >-
      Upload files of any type and get a link to use in tasks, sessions and
      messages. Agents should use the `upload_file` tool, which returns a
      project-wide `file@<id>` handle (`<id>` is the file `id` below).
  - name: Inboxes
    description: >-
      Test email addresses on @empiricalrun.email that a project claims. Only
      the claiming project can read an inbox, and only mail received after the
      claim. Typical flow: claim an address, sign up or log in to your app with
      it, then list the inbox's messages. Inboxes can also send mail, e.g. to
      test an app that processes inbound email: to @empiricalrun.email
      addresses, to anyone who emailed the inbox, and to the project's allowed
      recipients. Replies land back in the sending inbox.
  - name: Infra
    description: >-
      Infrastructure details customers configure against, such as static egress
      IPs.
  - name: Reporter Configuration
    description: Reporters a project can use in environment and run reporter configs.
  - name: Webhook Captures
    description: >-
      Throwaway URLs that record every request sent to them, for testing
      webhooks your app sends.
paths:
  /api/inboxes/send:
    post:
      tags:
        - Inboxes
      summary: Send an email
      description: >-
        Sends an email from an @empiricalrun.email address, with optional
        attachments. Each recipient must be an @empiricalrun.email address,
        someone who emailed the sender (with DMARC passing), or one of the
        project's allowed recipients (see Allowed recipients). Use it to test
        apps that receive email (reply-by-email, email-to-ticket, forwarding).
        Replies arrive in the sender's inbox; read them with
        `listAddressMessages`. Limits: 5 recipients and 5 attachments (5 MiB in
        total) per email; 10 emails per minute and 100 per rolling 24 hours per
        project. Emails whose recipients are all @empiricalrun.email addresses
        have separate, higher limits: 60 per minute and 1000 per rolling 24
        hours. Over a limit the request fails with 429.
      operationId: sendInboxMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendInboxMessageRequest'
      responses:
        '201':
          description: The email was accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendInboxMessageResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The sender or a recipient is not allowed, or sending is paused for
            this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: A send rate limit was reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The inbox service is not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The email provider rejected the email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SendInboxMessageRequest:
      type: object
      properties:
        from:
          type: string
          format: email
          description: >-
            Sender, an @empiricalrun.email address that is unclaimed or claimed
            by this project. Replies arrive in its inbox.
          example: support-sender-k3f9@empiricalrun.email
        to:
          type: array
          items:
            type: string
            format: email
          minItems: 1
          maxItems: 5
          description: >-
            Recipients. Each must be an @empiricalrun.email address, someone who
            emailed the sender, or one of the project's allowed recipients.
        cc:
          type: array
          items:
            type: string
            format: email
          maxItems: 5
          description: CC recipients.
        bcc:
          type: array
          items:
            type: string
            format: email
          maxItems: 5
          description: BCC recipients.
        reply_to:
          type: string
          format: email
          description: >-
            Reply-To address, if not `from`. Must be an @empiricalrun.email
            address.
        subject:
          type: string
          minLength: 1
          maxLength: 998
          description: Subject line.
        text:
          type: string
          description: Plain-text body.
        html:
          type: string
          description: HTML body.
        in_reply_to:
          type: string
          minLength: 1
          description: >-
            `message_id` of the email this replies to. Sets In-Reply-To and
            References so the reply threads.
        references:
          type: array
          items:
            type: string
            minLength: 1
          description: Full References chain, oldest first. Defaults to `in_reply_to`.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/InboxAttachment'
          maxItems: 5
          description: Up to 5 files, 5 MiB in total.
      required:
        - from
        - to
        - subject
    SendInboxMessageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            message_id:
              type: string
              description: >-
                Message-ID of the sent email. Replies to it carry it in
                In-Reply-To.
            sent_at:
              type: string
              description: ISO 8601 send time.
          required:
            - message_id
            - sent_at
          description: Response payload.
      required:
        - data
    ErrorResponse:
      type: object
      properties:
        data:
          nullable: true
          description: Always null for error responses.
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message.
          required:
            - message
          description: Error details.
      required:
        - data
        - error
    InboxAttachment:
      type: object
      properties:
        filename:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            File name shown to the recipient. Its extension sets the type and
            must be one of: csv, doc, docx, eml, gif, heic, ics, jpeg, jpg,
            json, md, odp, ods, odt, pdf, png, ppt, pptx, tsv, txt, webp, xls,
            xlsx, xml.
        content:
          type: string
          description: File contents, base64-encoded.
      required:
        - filename
        - content
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.