Genaya

API Reference
SupportkeyGet API key
Communication

Messages

Outbound SMS and MMS, plus the organization's message history.

GET/messages

List messages

Returns a cursor-paginated list of the organization's SMS and MMS message history, newest ids last. Requires scope: messages:read.

Parameters

Query

direction
string
Return only messages sent or only messages received.
conversationId
string
Return only messages in one conversation thread.

Response 200

No fields.

Errors

400Malformed or missing parameters
401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
429Rate limited
500Unexpected server error
POST/messages

Send a message

Sends an SMS or MMS from one of the organization's numbers. Requires scope: messages:write. Billing is per carrier segment, so a long body costs more than a short one. The organization's prepaid balance is checked before anything is sent - an organization whose balance is used up gets 403 insufficient_balance and no message leaves. Strongly consider sending an Idempotency-Key. It matters more here than anywhere else in the API: a retried request without one can send the same text twice, which costs money and annoys the recipient.

Request body

FieldTypeDescription
torequired
string
Recipient phone number in E.164 format, for example +14155550142.
body
string
The message text. Either body or mediaUrls (or both) must be provided. Longer bodies are not truncated - they are billed as more segments.
mediaUrls
array of string
Publicly reachable https:// URLs to attach as MMS media.
from
string
Which of the organization's numbers to send from, in E.164 format. When omitted, the company's configured outbound SMS number is used, falling back to any SMS-capable number the organization owns.
companyId
string
Send using this company's configured outbound number. Ignored when from is supplied explicitly.

Response 201

FieldTypeDescription
id
string
Unique identifier of the message.
object
string
direction
enuminbound | outbound
Whether the message was sent by the organization or received from a contact.
from
string
The sending phone number in E.164 format.
to
string
The receiving phone number in E.164 format.
body
string
The message text.
media
array of object
Attached media, when the message is an MMS.
url
string
contentType
string
nullable
segments
integer
Carrier segments the message was split into. Billing is per segment, so a long body costs more than a short one.nullable
status
string
Delivery status reported by the carrier.nullable
conversationId
string
The conversation thread this message belongs to.nullable
companyId
string
The company the sending number belongs to.nullable
createdAt
string <date-time>

Errors

400Malformed or missing parameters
401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
409Idempotency-Key reused with a different body
422Rejected by a business rule
429Rate limited
500Unexpected server error
GET/messages/{id}

Retrieve a message

Returns a single message by id. A message belonging to another organization returns 404 rather than 403. Requires scope: messages:read.

Parameters

Path

idrequired
string

Response 200

FieldTypeDescription
id
string
Unique identifier of the message.
object
string
direction
enuminbound | outbound
Whether the message was sent by the organization or received from a contact.
from
string
The sending phone number in E.164 format.
to
string
The receiving phone number in E.164 format.
body
string
The message text.
media
array of object
Attached media, when the message is an MMS.
url
string
contentType
string
nullable
segments
integer
Carrier segments the message was split into. Billing is per segment, so a long body costs more than a short one.nullable
status
string
Delivery status reported by the carrier.nullable
conversationId
string
The conversation thread this message belongs to.nullable
companyId
string
The company the sending number belongs to.nullable
createdAt
string <date-time>

Errors

401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
404No such resource in this organization
429Rate limited
500Unexpected server error