Skip to main content
POST
/
v1
/
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!"
  }'

{
  "success": true,
  "results": [
    {
      "to": "+15551234567",
      "success": true
    }
  ]
}
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!"
  }'

​
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:
FormatExample
E.164+15551234567
10-digit5551234567
With dashes555-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

API key provided by Nautilus. Pass as Authorization: Bearer <token>. Two key types are accepted: tenant-scoped keys (bound to a specific organization, used by most integrations) and legacy platform keys (send as the Nautilus brand). See the Introduction for details.

Body

application/json
​
to
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.

​
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.