> ## 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 SMS

> Send an SMS message to one or more recipients. Each recipient's phone number is validated and formatted to E.164 before sending. When sending to multiple recipients, the message is dispatched in parallel and individual results are returned for each recipient.

Tenant-scoped keys send via the organization's configured phone number; pass `useShortcode: true` to override and use the shared Nautilus shortcode. Platform keys always use the shortcode.

<RequestExample>
  ```bash Single recipient theme={null}
  curl -X POST https://app.nautilus.co/api/v1/message \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15551234567",
      "body": "Your wash is ready!"
    }'
  ```

  ```bash Multiple recipients theme={null}
  curl -X POST https://app.nautilus.co/api/v1/message \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": ["+15551234567", "+15559876543"],
      "body": "Flash sale: 50% off unlimited plans today!"
    }'
  ```

  ```bash With attachment (MMS) theme={null}
  curl -X POST https://app.nautilus.co/api/v1/message \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15551234567",
      "body": "Check out our new wash packages!",
      "attachments": [
        { "url": "https://example.com/promo.png" }
      ]
    }'
  ```

  ```bash Tenant-scoped key — override to Nautilus shortcode theme={null}
  curl -X POST https://app.nautilus.co/api/v1/message \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15551234567",
      "body": "Hello from the shortcode",
      "useShortcode": true
    }'
  ```
</RequestExample>

## Sender

Messages sent with a **tenant-scoped key** are delivered through your organization's configured phone number. Pass `useShortcode: true` in the request body to override and route through the shared Nautilus shortcode instead. Tenants without a configured phone number that omit `useShortcode` receive a `422` response.

Messages sent with a **platform key** always use the Nautilus shortcode; `useShortcode` is ignored on this path.

## Phone number formats

The `to` field accepts US phone numbers in several formats:

| Format      | Example        |
| ----------- | -------------- |
| E.164       | `+15551234567` |
| 10-digit    | `5551234567`   |
| With dashes | `555-123-4567` |

All numbers are validated and normalized to E.164 (`+1XXXXXXXXXX`) before delivery.

## Multi-send behavior

When sending to multiple recipients, each message 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 (invalid number, delivery error) do not block other recipients.

## Errors

* **400** — Validation error
* **401** — Missing or invalid Bearer token
* **422** — Tenant-scoped key with no configured phone number, and `useShortcode` was not set. Configure a phone number or pass `useShortcode: true`.
* **500** — Internal server error


## OpenAPI

````yaml POST /api/v1/message
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/message:
    post:
      tags:
        - Messaging
        - Legacy
      summary: Send SMS
      description: >-
        Send an SMS message to one or more recipients. Each recipient's phone
        number is validated and formatted to E.164 before sending. When sending
        to multiple recipients, the message is dispatched in parallel and
        individual results are returned for each recipient.


        Tenant-scoped keys send via the organization's configured phone number;
        pass `useShortcode: true` to override and use the shared Nautilus
        shortcode. Platform keys always use the shortcode.
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '200':
          description: All messages sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
              example:
                success: true
                results:
                  - to: '+15551234567'
                    success: true
        '207':
          description: Partial success — at least one recipient failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
              example:
                success: false
                results:
                  - to: '+15551234567'
                    success: true
                  - to: '+15559999999'
                    success: false
                    error: Invalid phone number
        '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 SMS sending. The tenant has no sending
            phone number and the request did not set `useShortcode: true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  Phone number sending is not configured for this tenant.
                  Contact support to configure phone number sending, or pass
                  `useShortcode: true`.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
components:
  schemas:
    SendMessageRequest:
      type: object
      required:
        - to
        - body
      properties:
        to:
          description: >-
            Recipient phone number(s). Accepts a single number or an array.
            Numbers can be in E.164 format (`+15551234567`), raw 10-digit
            (`5551234567`), or other common US formats.
          oneOf:
            - type: string
              minLength: 1
              examples:
                - '+15551234567'
            - type: array
              items:
                type: string
                minLength: 1
              minItems: 1
              examples:
                - - '+15551234567'
                  - '+15559876543'
        body:
          type: string
          minLength: 1
          description: The text content of the SMS message.
        attachments:
          type: array
          description: >-
            Optional list of media attachments (MMS). Each attachment must
            include a publicly accessible URL.
          items:
            type: object
            required:
              - url
            properties:
              url:
                type: string
                format: uri
                description: Publicly accessible URL of the media file.
        useShortcode:
          type: boolean
          description: >-
            Only meaningful for tenant-scoped keys. When `true`, the message is
            routed through the shared Nautilus shortcode instead of the tenant's
            configured phone number. Ignored on platform keys (they always use
            the shortcode). Default: `false`.
          default: false
    SendMessageResponse:
      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/RecipientResult'
    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
    RecipientResult:
      type: object
      required:
        - to
        - success
      properties:
        to:
          type: string
          description: The E.164-formatted phone number the message was sent to.
        success:
          type: boolean
          description: Whether the message was sent successfully to this recipient.
        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.

````