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

# Send computer email

> Immediately sends a real email from the computer's stable inbox address. Call this only after the user approves the recipient and content, and send an Idempotency-Key so a network retry cannot send it twice.



## OpenAPI

````yaml https://www.cool.computer/openapi.json post /api/computers/{id}/emails/send
openapi: 3.1.0
info:
  title: Cool Computers API
  version: 1.0.0
  description: >-
    Create and operate reachable Linux computers. Each computer keeps a stable
    name.cool.computer address, persistent files, and agent-ready command
    execution. REST requests use UTC-aligned one-minute limits: 600 requests per
    account identified by a recognized valid account bearer credential, a
    separate 600-request budget per computer-scoped credential, or 60 requests
    per source IP otherwise. Read-only GETs answered from API state spend a
    separate read budget reported as account-read or computer-read, so status
    polling cannot exhaust the budget that protects work and mutations. To bound
    authentication-provider traffic, at most 60 first-seen bearer values are
    checked per source IP in a minute; recognized valid credentials use their
    account or computer policy. Successful bearer authentication is reused for
    at most five seconds; transient provider failures are not cached. Non-exempt
    API responses include the structured RateLimit and RateLimit-Policy fields;
    request admission 429 responses use code api_request_rate_exceeded and also
    include Retry-After. Health, OpenAPI, webhooks, callbacks, SSE, and
    WebSocket endpoints are exempt from the REST request budget. Authenticated
    SSE connection attempts remain subject to the authentication safeguards and
    can receive the same typed 429 response.
servers:
  - url: https://api.cool.computer
    description: Canonical API origin
security: []
tags:
  - name: Authentication
    description: Obtain and manage bearer credentials.
  - name: Billing
    description: Inspect and manage the account's no-card trial or Pro plan.
  - name: Computers
    description: Create, inspect, and delete resident computers.
  - name: Execution
    description: Run commands on a computer.
  - name: Files
    description: Read and change a computer's persistent files.
  - name: Publishing
    description: >-
      Publish files to a computer's URL as immutable releases, with no VM. To
      show something, publish the files; to run something, use the computer
      (exec, terminal, services), which gets Linux on first use.
  - name: Services
    description: >-
      Manage processes and select the HTTP port exposed at a computer's stable
      address.
  - name: Email
    description: Read and send mail through a computer's inbox.
  - name: Network
    description: Control a computer's public visibility and outbound network policy.
  - name: Sharing
    description: Invite people to use a computer without granting owner controls.
  - name: Public
    description: Unauthenticated discovery endpoints.
externalDocs:
  description: Cool Computers agent registration guide
  url: https://www.cool.computer/auth.md
paths:
  /api/computers/{id}/emails/send:
    post:
      tags:
        - Email
      summary: Send computer email
      description: >-
        Immediately sends a real email from the computer's stable inbox address.
        Call this only after the user approves the recipient and content, and
        send an Idempotency-Key so a network retry cannot send it twice.
      operationId: sendComputerEmail
      parameters:
        - $ref: '#/components/parameters/ComputerID'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailSendRequest'
      responses:
        '201':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: One inbound or outbound email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessage'
        '400':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Bad Request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: >-
            Payment Required. The trial expired or Pro is inactive; inspect the
            problem code and resolution.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Forbidden.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Not Found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: >-
            The idempotency key is in progress, has an unknown outcome, or was
            used for a different request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '413':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Payload Too Large.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          description: >-
            Too Many Requests. If the problem code is api_request_rate_exceeded,
            wait for Retry-After seconds; other problem codes describe a
            separate limit.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Internal Server Error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: Service Unavailable.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        default:
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          description: >-
            A machine-readable API error with a stable code and recovery
            instruction.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  parameters:
    ComputerID:
      name: id
      in: path
      required: true
      description: Stable public computer identifier.
      schema:
        type: string
        minLength: 1
        example: cmp_123
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        A caller-generated key for safely retrying this side effect. The server
        retains the key and response for 24 hours. Reusing it with the same
        request replays the original response; reusing it with different input
        returns 409.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[!-~]+$
        example: req_01J6M6Y9TF9Q9QF6M1ZP8K4R2A
  schemas:
    EmailSendRequest:
      type: object
      additionalProperties: false
      required:
        - to
        - subject
      anyOf:
        - required:
            - text
        - required:
            - html
      properties:
        to:
          type: string
          format: email
        subject:
          type: string
          minLength: 1
          description: Subject line, limited to 998 bytes.
        text:
          type: string
          description: >-
            Plain-text body. The text and HTML bodies together are limited to 1
            MiB.
        html:
          type: string
          description: HTML body. The text and HTML bodies together are limited to 1 MiB.
    EmailMessage:
      type: object
      additionalProperties: false
      required:
        - id
        - direction
        - status
        - from
        - envelope_from
        - to
        - subject
        - created_at
      properties:
        id:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        status:
          type: string
          enum:
            - received
            - pending
            - sent
            - failed
            - ambiguous
            - rejected
        from:
          type: string
        envelope_from:
          type: string
        sender_authentication:
          type: string
        authenticated_sender:
          type: string
        to:
          type: array
          items:
            type: string
        subject:
          type: string
        text:
          type: string
        html:
          type: string
        message_id:
          type: string
        in_reply_to:
          type: string
        error:
          type: string
        read_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    Problem:
      type: object
      additionalProperties: false
      required:
        - type
        - title
        - status
        - code
        - detail
        - resolution
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        code:
          type: string
          pattern: ^[a-z0-9_]+$
        detail:
          type: string
        resolution:
          type: string
        context:
          type: object
          additionalProperties: true
  headers:
    RateLimit:
      description: >-
        The applied policy name, requests remaining after this request, and
        whole seconds until the current UTC-aligned window resets.
      schema:
        type: string
        pattern: >-
          ^"(account|account-read|computer|computer-read|source)";r=[0-9]+;t=([1-9]|[1-5][0-9]|60)$
        examples:
          - '"account";r=599;t=42'
          - '"computer-read";r=598;t=42'
    RateLimit-Policy:
      description: >-
        The selected policy name, quota, and window in seconds. Valid account
        credentials use account or account-read with q=600, computer credentials
        use computer or computer-read with q=600, and unauthenticated or
        unrecognized requests use source with q=60 for their source IP.
      schema:
        type: string
        pattern: >-
          ^("(account|account-read|computer|computer-read)";q=600|"source";q=60);w=60$
        examples:
          - '"account";q=600;w=60'
          - '"computer-read";q=600;w=60'
    Retry-After:
      description: >-
        Whole seconds to wait after an api_request_rate_exceeded response before
        retrying. Other 429 problem codes describe separate resource or provider
        limits and do not inherit this retry value.
      schema:
        type: integer
        minimum: 1
        maximum: 60
        examples:
          - 42
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: WorkOS user or agent access token, or Cool Computers API key
      description: >-
        A Cool Computers API key, user access token, or claimed agent access
        token in the Authorization header. Follow
        https://www.cool.computer/auth.md for agent registration and
        https://www.cool.computer/authentication.md for direct user credentials.

````