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!"
  }'

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!"
  }'

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" }
    ]
  }'

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
  }'

{
  "success": true,
  "results": [
    {
      "to": "+15551234567",
      "success": true
    }
  ]
}

{
  "success": false,
  "results": [
    {
      "to": "+15551234567",
      "success": true
    },
    {
      "to": "+15559999999",
      "success": false,
      "error": "Invalid phone number"
    }
  ]
}

{
  "error": "Invalid request format",
  "details": [
    {
      "code": "<string>",
      "message": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "error": "Unauthorized"
}

{
  "error": "Phone number sending is not configured for this tenant. Contact support to configure phone number sending, or pass `useShortcode: true`."
}

{
  "error": "<string>"
}

Message

Send SMS

deprecated

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.

POST

api

message

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!"
  }'

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!"
  }'

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" }
    ]
  }'

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
  }'

{
  "success": true,
  "results": [
    {
      "to": "+15551234567",
      "success": true
    }
  ]
}

{
  "success": false,
  "results": [
    {
      "to": "+15551234567",
      "success": true
    },
    {
      "to": "+15559999999",
      "success": false,
      "error": "Invalid phone number"
    }
  ]
}

{
  "error": "Invalid request format",
  "details": [
    {
      "code": "<string>",
      "message": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "error": "Unauthorized"
}

{
  "error": "Phone number sending is not configured for this tenant. Contact support to configure phone number sending, or pass `useShortcode: true`."
}

{
  "error": "<string>"
}

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!"
  }'

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!"
  }'

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" }
    ]
  }'

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
  }'

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

Authorizations

Authorization

string

header

required

Clerk tenant API key. The organizationId encoded by the key is the exact and only tenant scope.

Body

application/json

required

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.

Minimum string length: 1

Example:

"+15551234567"

body

string

required

The text content of the SMS message.

Minimum string length: 1

attachments

object[]

Optional list of media attachments (MMS). Each attachment must include a publicly accessible URL.

Show child attributes

useShortcode

boolean

default:false

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.

Response

All messages sent successfully

success

boolean

required

true when every recipient was sent successfully, false otherwise.

results

object[]

required

Per-recipient delivery results.

Show child attributes

API documentation

Sites

Products

Checkout links

Purchases

Contacts

Marketing

Forms

Vouchers

Links

Automations

Surveys

Cases

Cancellations

Sonny's POS

Message

Email

Analytics

Integration

Send SMS

Sender

Phone number formats

Multi-send behavior

Errors

Authorizations

Body

Response

​Sender

​Phone number formats

​Multi-send behavior

​Errors

Authorizations

Body

Response

Sender

Phone number formats

Multi-send behavior

Errors