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

# Send email

> Send an email to one or more recipients. Each recipient is processed independently in parallel.

The allowed `from` address depends on the key type. Tenant-scoped keys must send from `{slug}@mail.nautilus.co` (default `{Tenant Name} <{slug}@mail.nautilus.co>`); platform keys must use `@mail.nautilus.co` (default `Nautilus <contact@mail.nautilus.co>`).

<RequestExample>
  ```bash Single recipient theme={null}
  curl -X POST https://app.nautilus.co/api/v1/email \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "customer@example.com",
      "subject": "Your monthly wash summary",
      "html": "<h1>Hi!</h1><p>You washed 12 times this month.</p>"
    }'
  ```

  ```bash Multiple recipients theme={null}
  curl -X POST https://app.nautilus.co/api/v1/email \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": ["customer@example.com", "other@example.com"],
      "subject": "Flash sale this weekend",
      "html": "<p>50% off unlimited plans — this weekend only!</p>"
    }'
  ```

  ```bash Custom from and reply-to theme={null}
  curl -X POST https://app.nautilus.co/api/v1/email \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "customer@example.com",
      "subject": "Welcome to Squeaky Clean Car Wash",
      "html": "<p>Thanks for joining!</p>",
      "from": "Squeaky Clean <squeaky@mail.nautilus.co>",
      "replyTo": "support@squeakyclean.com"
    }'
  ```

  ```bash With attachment (URL) theme={null}
  curl -X POST https://app.nautilus.co/api/v1/email \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "customer@example.com",
      "subject": "Your invoice",
      "html": "<p>Please find your invoice attached.</p>",
      "attachments": [
        { "filename": "invoice.pdf", "path": "https://example.com/invoices/123.pdf" }
      ]
    }'
  ```
</RequestExample>

## Sender address

The `from` field is optional. The allowed values depend on the type of API key you use (see [Key types](/api-reference/introduction#key-types)).

**Tenant-scoped keys** — the default sender is `{Tenant Name} <{slug}@mail.nautilus.co>`, where `{slug}` is your organization's slug. If you provide `from` explicitly, the email address must be exactly `{slug}@mail.nautilus.co`; you may customize the display name:

```
Squeaky Clean Promos <squeaky-clean@mail.nautilus.co>
```

Tenants without a configured slug receive a `422` response.

**Platform keys** — the default sender is `Nautilus <contact@mail.nautilus.co>`. If you provide `from` explicitly, the address must use the `@mail.nautilus.co` domain.

## Attachments

Add files to an email with the `attachments` array. Each attachment requires a `filename` and either:

* **`path`** — a publicly accessible URL to the file
* **`content`** — the file as a base64-encoded string

| Field    | Type   | Required | Description                                 |
| -------- | ------ | -------- | ------------------------------------------- |
| filename | string | Yes      | Filename with extension (e.g. `report.pdf`) |
| path     | string | No       | Public URL to the file                      |
| content  | string | No       | Base64-encoded file content                 |

<Note>Each attachment must include either `path` or `content`, but not both.</Note>

## Multi-send behavior

When sending to multiple recipients, each email is dispatched in parallel. The response includes per-recipient results:

* **200** — All recipients succeeded
* **207** — At least one recipient failed (check `results` for details)

Individual failures do not block other recipients. Successful results include an `id` field for tracking.

## Errors

* **400** — Validation error, including a `from` address that doesn't match the rules for your key type
* **401** — Missing or invalid Bearer token
* **422** — Your tenant is not configured for email sending. Contact Nautilus support.
* **500** — Internal server error


## OpenAPI

````yaml POST /api/v1/email
openapi: 3.1.0
info:
  title: Nautilus Public API
  version: 1.0.0
  description: >-
    Tenant-scoped public API. Except for /api/v1/openapi.json, requests use a
    Clerk tenant API key as a Bearer token. The key's organizationId is the sole
    tenant scope; organization IDs supplied by callers are never accepted.
    Detail endpoints deliberately return 404 for both missing and cross-tenant
    records. Canonical collections use the standard envelope and endpoint-bound
    cursor pagination. Timestamps are UTC ISO 8601 values and monetary amounts
    ending in Cents are integer cents. Responses use narrow serializers and
    exclude credentials, API keys, provider configuration, access tokens,
    webhook secrets, raw provider payloads, and internal workflow or activity
    data.
servers:
  - url: https://app.nautilus.co
security:
  - tenantApiKey: []
tags:
  - name: Contract
  - name: Cancellations
  - name: Sites
  - name: Products
  - name: Checkout links
  - name: Purchases
  - name: Contact lists
  - name: Contacts
  - name: Marketing
  - name: Forms
  - name: Vouchers
  - name: Links
  - name: Automations
  - name: Surveys
  - name: Cases
  - name: Sonny's POS
  - name: Analytics
  - name: Messaging
  - name: Legacy
    description: Deprecated noncanonical endpoints retained for compatibility.
paths:
  /api/v1/email:
    post:
      tags:
        - Messaging
        - Legacy
      summary: Send email
      description: >-
        Send an email to one or more recipients. Each recipient is processed
        independently in parallel.


        The allowed `from` address depends on the key type. Tenant-scoped keys
        must send from `{slug}@mail.nautilus.co` (default `{Tenant Name}
        <{slug}@mail.nautilus.co>`); platform keys must use `@mail.nautilus.co`
        (default `Nautilus <contact@mail.nautilus.co>`).
      operationId: sendEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '200':
          description: All emails sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
              example:
                success: true
                results:
                  - to: customer@example.com
                    success: true
                    id: abc123
        '207':
          description: Partial success — at least one recipient failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
              example:
                success: false
                results:
                  - to: customer@example.com
                    success: true
                    id: abc123
                  - to: invalid@
                    success: false
                    error: Invalid email address
        '400':
          description: Validation error — request body does not match the expected schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
        '422':
          description: >-
            Tenant is not configured for email sending (no slug on the tenant
            organization).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  Email sending is not configured for this tenant. Contact
                  support.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
components:
  schemas:
    SendEmailRequest:
      type: object
      required:
        - to
        - subject
        - html
      properties:
        to:
          description: Recipient email address(es). Accepts a single address or an array.
          oneOf:
            - type: string
              format: email
              examples:
                - customer@example.com
            - type: array
              items:
                type: string
                format: email
              minItems: 1
              examples:
                - - customer@example.com
                  - other@example.com
        subject:
          type: string
          minLength: 1
          description: The email subject line.
        html:
          type: string
          minLength: 1
          description: The email body as HTML.
        from:
          type: string
          description: >-
            Sender address. Allowed values depend on key type. **Tenant-scoped
            keys**: the email address part must be exactly
            `{slug}@mail.nautilus.co` where `{slug}` is the organization's slug;
            the display name is free-form. Default: `{Tenant Name}
            <{slug}@mail.nautilus.co>`. **Platform keys**: must use the
            `@mail.nautilus.co` domain. Default: `Nautilus
            <contact@mail.nautilus.co>`.
        replyTo:
          type: string
          format: email
          description: Optional reply-to email address.
        attachments:
          type: array
          description: >-
            Optional file attachments. Each must include a `filename` and either
            a `path` (public URL) or `content` (base64-encoded string).
          items:
            $ref: '#/components/schemas/EmailAttachment'
    SendEmailResponse:
      type: object
      required:
        - success
        - results
      properties:
        success:
          type: boolean
          description: >-
            `true` when every recipient was sent successfully, `false`
            otherwise.
        results:
          type: array
          description: Per-recipient delivery results.
          items:
            $ref: '#/components/schemas/EmailRecipientResult'
    ValidationError:
      type: object
      required:
        - error
        - details
      properties:
        error:
          type: string
          example: Invalid request format
        details:
          type: array
          description: Zod validation errors describing which fields failed.
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              path:
                type: array
                items:
                  type: string
    Error:
      type: object
      additionalProperties: false
      properties:
        error:
          type: string
      required:
        - error
    EmailAttachment:
      type: object
      required:
        - filename
      properties:
        filename:
          type: string
          minLength: 1
          description: The filename including extension (e.g. `report.pdf`).
        path:
          type: string
          format: uri
          description: >-
            A publicly accessible URL to the file. Provide either `path` or
            `content`.
        content:
          type: string
          description: Base64-encoded file content. Provide either `path` or `content`.
    EmailRecipientResult:
      type: object
      required:
        - to
        - success
      properties:
        to:
          type: string
          description: The recipient email address.
        success:
          type: boolean
          description: Whether the email was sent successfully to this recipient.
        id:
          type: string
          description: Email ID returned on success.
        error:
          type: string
          description: Error message if delivery failed for this recipient.
  securitySchemes:
    tenantApiKey:
      type: http
      scheme: bearer
      bearerFormat: Clerk tenant API key
      description: >-
        Clerk tenant API key. The organizationId encoded by the key is the exact
        and only tenant scope.

````