Skip to main content
POST
/
phone
/
send-sms
cURL
curl --request POST \
  --url https://api.useanima.sh/v1/phone/send-sms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "<string>",
  "to": "<string>",
  "body": "<string>",
  "mediaUrls": [],
  "metadata": {}
}
'
{
  "id": "<string>",
  "agentId": "<string>",
  "fromAddress": "<string>",
  "toAddress": "<string>",
  "subject": "<string>",
  "body": "<string>",
  "bodyHtml": "<string>",
  "headers": {},
  "metadata": {},
  "threadId": "<string>",
  "inReplyTo": "<string>",
  "externalId": "<string>",
  "sentAt": "2023-11-07T05:31:56Z",
  "receivedAt": "2023-11-07T05:31:56Z",
  "attachments": [
    {
      "id": "<string>",
      "filename": "<string>",
      "mimeType": "<string>",
      "sizeBytes": 1,
      "storageKey": "<string>",
      "url": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "detectedMimeType": "<string>"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Request body for sending an SMS or MMS through an agent

agentId
string
required

ID of the agent sending the SMS

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
to
string
required

Recipient phone number in E.164 format

Required string length: 7 - 20
body
string
required

Text content of the SMS message (max 1600 characters)

Required string length: 1 - 1600
mediaUrls
string<uri>[]

URLs of media attachments for MMS (max 10)

Maximum array length: 10
metadata
object

Arbitrary key-value metadata to attach to the message

Response

200 - application/json

OK

Full message resource representation

id
string
required

Unique identifier of the message

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
agentId
string
required

ID of the agent that sent or received the message

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
channel
enum<string>
required

Communication channel used

Available options:
EMAIL,
SMS,
MMS,
VOICE
direction
enum<string>
required

Whether the message was inbound or outbound

Available options:
INBOUND,
OUTBOUND
status
enum<string>
required

Current delivery status

Available options:
QUEUED,
SENT,
DELIVERED,
FAILED,
BOUNCED,
BLOCKED,
PENDING_APPROVAL
fromAddress
string
required

Sender address (email or phone number)

toAddress
string
required

Recipient address (email or phone number)

subject
string | null
required

Message subject line, or null for channels that do not support subjects

body
string
required

Plain-text content of the message

bodyHtml
string | null
required

HTML content of the message, or null if not available

headers
object | null
required

Raw message headers as key-value pairs, or null

metadata
object | null
required

Arbitrary metadata attached to the message, or null

threadId
string | null
required

Thread identifier for conversation grouping, or null

inReplyTo
string | null
required

Message ID this message is replying to, or null

externalId
string | null
required

Provider-assigned external identifier, or null

sentAt
string<date-time> | null
required

Timestamp when the message was sent, or null if not yet sent

receivedAt
string<date-time> | null
required

Timestamp when the message was received, or null for outbound messages

attachments
object[]
required

File attachments associated with this message

createdAt
string<date-time>
required

Timestamp when the message record was created

updatedAt
string<date-time>
required

Timestamp when the message record was last updated