Documentation

Messages

These endpoints let you send SMS messages and read the inbound messages received on your Guava numbers — for example, to poll your own inbox for replies.

All requests require an Authorization: Bearer YOUR_GUAVA_API_KEY header. See the API Overview for details.

Send an SMS

POST /v1/send-sms

Send a single SMS from one of your Guava numbers.

Request body

A JSON object with the following fields:

Name	Type	Required	Description
`from_number`	string	Yes	One of your Guava numbers, in E.164 format. Must have SMS enabled.
`to_number`	string	Yes	The recipient's number, in E.164 format.
`message`	string	Yes	The message body to send.

Response

On success, returns 201 Created:

{
  "status": "sent"
}

Errors

Status	Description
400	The `from_number` isn't owned by your organization, or doesn't have SMS configured.
401	Invalid authentication
500	The upstream carrier failed to accept the message.

Example

curl -X POST https://api.goguava.ai/v1/send-sms \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"from_number": "+15551230001", "to_number": "+15551234567", "message": "Hello from Guava!"}'

Sending SMS requires your organization to complete SMS brand and campaign registration. See Outbound & SMS Permissions.

List inbound messages

GET /v1/messages

List the inbound messages received on one of your Guava numbers, oldest first. Poll this endpoint to watch for replies.

Parameters

Name	Type	Required	Description
`to_number`	string	Yes	The Guava number whose inbox you want to read, in E.164 format. Must be owned by your organization.
`start`	string	No	Only return messages received at or after this time (ISO 8601, e.g. `2026-06-09T00:00:00Z`).
`from_number`	string	No	Only return messages sent from this number, in E.164 format.
`modality`	string	No	Only return messages on this channel. Currently `"sms"`.
`limit`	integer	No	Maximum number of messages to return, between 1 and 100. Defaults to 50.

Response

A JSON object with the following fields:

Field	Type	Description
`messages`	array	The matching messages, oldest first.
`has_more`	boolean	`true` if more messages match than were returned in this response.

Each message has the following fields:

Field	Type	Description
`id`	string	Unique ID of the message
`from_number`	string	The number that sent the message
`to_number`	string	Your Guava number that received the message
`content`	string	The message body
`received_at`	string	When the message was received, in ISO 8601 format
`modality`	string	The channel the message arrived on. Currently `"sms"`.
`direction`	string	Always `"inbound"`

Pagination

Messages are returned oldest first. When has_more is true, request the next page by calling again with start set to the received_at of the last message you received. Because start is inclusive, that boundary message — and any others sharing its exact timestamp — will be returned again, so dedupe by id.

Errors

Status	Description
400	Invalid `start` timestamp or `limit` value
401	Invalid authentication
404	The `to_number` isn't owned by your organization

Example

curl -G https://api.goguava.ai/v1/messages \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  --data-urlencode 'to_number=+15551230001' \
  --data-urlencode 'start=2026-06-09T00:00:00Z'

Sample response:

{
  "messages": [
    {
      "id": "6064ab9663dc4eb0",
      "from_number": "+15551234567",
      "to_number": "+15551230001",
      "content": "YES, see you then!",
      "received_at": "2026-06-09T00:12:04.518000+00:00",
      "modality": "sms",
      "direction": "inbound"
    }
  ],
  "has_more": false
}

The + in a phone number must be URL-encoded as %2B in query strings. The curl -G --data-urlencode form above handles this for you.

Questions? hi@goguava.ai

curl -X POST https://api.goguava.ai/v1/send-sms \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"from_number": "+15551230001", "to_number": "+15551234567", "message": "Hello from Guava!"}'

curl -G https://api.goguava.ai/v1/messages \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  --data-urlencode 'to_number=+15551230001' \
  --data-urlencode 'start=2026-06-09T00:00:00Z'

{
  "messages": [
    {
      "id": "6064ab9663dc4eb0",
      "from_number": "+15551234567",
      "to_number": "+15551230001",
      "content": "YES, see you then!",
      "received_at": "2026-06-09T00:12:04.518000+00:00",
      "modality": "sms",
      "direction": "inbound"
    }
  ],
  "has_more": false
}