Mobilerun Messages API
The Messages API from Mobilerun — 5 operation(s) for messages.
Operations 5
POST
/numbers/messages/conversations/read
Mark a conversation's inbound messages read up to a cursor
#
The Messages API from Mobilerun — 5 operation(s) for messages.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/mobilerun-ai:mobilerun-ai-messages-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Mobilerun Ai Messages API
version: v1
contact:
name: Droidrun
email: support@droidrun.ai
description: 'Operations tagged Messages across 2 of this provider''s published API definitions: openapi.json, mobilerun-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
security:
- bearerAuth: []
tags:
- name: Messages
paths:
/numbers/messages:
get:
tags:
- Messages
summary: List the caller's own SMS inbox/outbox messages
operationId: listMessages
description: Lists SMS messages newest first, with filters for direction, eSIM, phone number, status, and conversation.
responses:
'200':
description: Messages retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/PublicMessageListResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Messaging is unavailable when phone numbers and all eSIM providers are disabled. See `code` for details.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
parameters:
- schema:
type: integer
exclusiveMinimum: 0
default: 1
required: false
name: page
in: query
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
required: false
name: pageSize
in: query
- schema:
type: string
enum:
- all
- inbound
- outbound
default: all
required: false
name: direction
in: query
- schema:
type: string
format: uuid
required: false
name: esimId
in: query
- schema:
type: string
format: uuid
required: false
name: numberId
in: query
- schema:
type: string
enum:
- all
- received
- queued
- claimed
- sending
- sent
- sent_unconfirmed
- delivered
- failed
default: all
description: Filter by message status. `delivered` and `sent_unconfirmed` are kept for compatibility and are not emitted on current lines.
required: false
description: Filter by message status. `delivered` and `sent_unconfirmed` are kept for compatibility and are not emitted on current lines.
name: status
in: query
- schema:
type: string
minLength: 3
maxLength: 64
required: false
name: peerNumber
in: query
- schema:
type: string
minLength: 1
maxLength: 128
required: false
name: peerKey
in: query
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
/numbers/messages/conversations:
get:
tags:
- Messages
summary: List the caller's own SMS conversations, one row per thread
operationId: listConversations
description: Lists SMS conversations by recent activity. Use both cursor fields from `nextCursor` to fetch the next page.
responses:
'200':
description: Conversations retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ListConversationsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Messaging is unavailable when phone numbers and all eSIM providers are disabled. See `code` for details.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
parameters:
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
required: false
name: limit
in: query
- schema:
type: string
format: uuid
required: false
name: esimId
in: query
- schema:
type: string
format: uuid
required: false
name: numberId
in: query
- schema:
type: string
format: date-time
required: false
name: cursorLastOccurredAt
in: query
- schema:
type: string
format: uuid
required: false
name: cursorLastMessageId
in: query
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
/numbers/messages/conversations/read:
post:
tags:
- Messages
summary: Mark a conversation's inbound messages read up to a cursor
operationId: markConversationRead
description: Marks inbound messages in a conversation as read through the supplied cursor. Repeating the request is safe.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MarkConversationReadInput'
responses:
'200':
description: Read state updated
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/MarkConversationReadResponse'
required:
- data
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Messaging is unavailable when phone numbers and all eSIM providers are disabled. See `code` for details.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
/numbers/messages/{id}:
get:
tags:
- Messages
summary: Get one of the caller's SMS messages
operationId: getMessage
description: Returns one message. For an outbound message that is not yet final, the status may be refreshed once (at most every 30 s) before it is returned; a failed refresh returns the stored message.
responses:
'200':
description: Message retrieved
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PublicMessageRow'
required:
- data
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Messaging is unavailable when phone numbers and all eSIM providers are disabled. See `code` for details.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
parameters:
- schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
required: true
name: id
in: path
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
/numbers/phones/{id}/messages:
post:
tags:
- Messages
summary: Send an SMS from a number
operationId: sendNumberMessage
description: 'Queues an SMS from one of the caller''s numbers that can send. Replaying an Idempotency-Key with the same payload returns the original message, reusing it with a different payload returns 422. 409 capability_unavailable: this number cannot send right now. 422 invalid_recipient / unsupported_destination / body_too_long: the recipient or text does not fit the number. 429 daily_limit_reached: the rolling 24 h limit for the account is used up; 429 rate_limited: too many sends by the owner in a short window; 429 number_rate_limited: too many outbound sends from this number in the configured window (all sends from this number count, including those made on your behalf). 403 send_disabled: self-service SMS send is switched off; outbound_sms_not_granted: outbound SMS requires an admin grant.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendPhoneMessageInput'
responses:
'202':
description: Outbound message queued
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
esimId:
type:
- string
- 'null'
format: uuid
direction:
type: string
enum:
- inbound
- outbound
status:
type: string
enum:
- received
- queued
- claimed
- sending
- sent
- sent_unconfirmed
- delivered
- failed
description: Message status. Outbound messages move queued → sending → sent, or end at failed. `sent` means the mobile network accepted the message and is the final success status. `delivered` and `sent_unconfirmed` are kept for compatibility; current lines return no carrier delivery report, so neither is emitted.
peerNumber:
type:
- string
- 'null'
peerKey:
type:
- string
- 'null'
body:
type:
- string
- 'null'
deliveryStatus:
type:
- string
- 'null'
detectedSender:
type:
- string
- 'null'
classification:
$ref: '#/components/schemas/MessageClassification'
occurredAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
required:
- id
- esimId
- direction
- status
- peerNumber
- peerKey
- body
- deliveryStatus
- detectedSender
- classification
- occurredAt
- createdAt
required:
- data
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'403':
description: Self-service SMS send is not enabled (send_disabled), or requires an admin grant (outbound_sms_not_granted).
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'409':
description: This number cannot send right now (capability_unavailable).
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'422':
description: invalid_recipient, unsupported_destination, body_too_long, or the Idempotency-Key was already used for a different request (idempotency_key_reused).
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'429':
description: Daily limit reached (daily_limit_reached), too many owner sends in a short window (rate_limited), or too many sends from this number (number_rate_limited).
content:
application/json:
schema:
$ref: '#/components/schemas/MessageErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: The phone-number service is unavailable. See `code` for details.
content:
application/json:
schema:
$ref: '#/components/schemas/NumberErrorResponse'
parameters:
- schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
required: true
name: id
in: path
- schema:
type: string
minLength: 1
maxLength: 255
pattern: ^[\x21-\x7E]{1,255}$
description: 'Idempotency-Key: 1-255 printable ASCII characters. Same key with a different request body is a 422 idempotency_key_reused. A retryable in-flight duplicate is a 409 with Retry-After and x-should-retry: true; a terminal duplicate is a 409 with x-should-retry: false. A replay returns the current resource state with Idempotent-Replayed: true.'
example: b3f6a9f0-6f1a-4e9a-9e7a-9c9b6b6a5a3f
required: false
description: 'Idempotency-Key: 1-255 printable ASCII characters. Same key with a different request body is a 422 idempotency_key_reused. A retryable in-flight duplicate is a 409 with Retry-After and x-should-retry: true; a terminal duplicate is a 409 with x-should-retry: false. A replay returns the current resource state with Idempotent-Replayed: true.'
name: idempotency-key
in: header
servers:
- url: https://api.mobilerun.ai
description: Droidrun Cloud API
components:
schemas:
PublicMessageRow:
type: object
properties:
id:
type: string
format: uuid
esimId:
type:
- string
- 'null'
format: uuid
direction:
type: string
enum:
- inbound
- outbound
status:
type: string
enum:
- received
- queued
- claimed
- sending
- sent
- sent_unconfirmed
- delivered
- failed
description: Message status. Outbound messages move queued → sending → sent, or end at failed. `sent` means the mobile network accepted the message and is the final success status. `delivered` and `sent_unconfirmed` are kept for compatibility; current lines return no carrier delivery report, so neither is emitted.
peerNumber:
type:
- string
- 'null'
peerKey:
type:
- string
- 'null'
body:
type:
- string
- 'null'
deliveryStatus:
type:
- string
- 'null'
detectedSender:
type:
- string
- 'null'
providerCode:
type:
- string
- 'null'
classification:
$ref: '#/components/schemas/MessageClassification'
occurredAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
required:
- id
- esimId
- direction
- status
- peerNumber
- peerKey
- body
- deliveryStatus
- detectedSender
- providerCode
- classification
- occurredAt
- createdAt
NumberErrorReason:
type: string
enum:
- product_disabled
- not_cancellable
- capability_unavailable
description: Stable machine-readable phone-number error code. Unknown future values should be handled as a generic error with the same HTTP status.
MessageErrorReason:
type: string
enum:
- not_installed
- missing_device
- missing_subscription
- idempotency_key_reused
- send_disabled
- outbound_sms_not_granted
- daily_cap_exceeded
- rate_limited
- capability_unavailable
- invalid_recipient
- unsupported_destination
- body_too_long
- daily_limit_reached
- number_rate_limited
- product_disabled
description: Stable machine-readable messaging error code. Unknown future values should be handled as a generic error with the same HTTP status.
MarkConversationReadInput:
type: object
properties:
peerKey:
type: string
minLength: 1
maxLength: 128
description: The thread's canonical peer key (see GET .../conversations)
upToOccurredAt:
type: string
format: date-time
description: Mark inbound messages read up to (and including) this occurredAt/upToMessageId cursor
upToMessageId:
type: string
format: uuid
required:
- peerKey
- upToOccurredAt
- upToMessageId
ApiErrorEnvelope:
type: object
properties:
code:
type: string
message:
type: string
details: {}
traceId:
type: string
retryAfterSeconds:
type: number
required:
- code
- message
ConversationRow:
type: object
properties:
peerKey:
type: string
lastMessage:
$ref: '#/components/schemas/ConversationLastMessage'
unreadCount:
type: integer
minimum: 0
esimIds:
type: array
items:
type: string
format: uuid
required:
- peerKey
- lastMessage
- unreadCount
- esimIds
ListConversationsResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ConversationRow'
nextCursor:
$ref: '#/components/schemas/ConversationCursor'
required:
- items
- nextCursor
MessageClassification:
type:
- object
- 'null'
properties:
spam:
type: boolean
required:
- spam
SendPhoneMessageInput:
type: object
properties:
to:
type: string
minLength: 1
maxLength: 32
example: '+15551230001'
description: Recipient phone number, as E.164 or a US 10/11-digit number. Destinations the number cannot send to are rejected with 422 unsupported_destination, non-numbers with 422 invalid_recipient.
body:
type: string
minLength: 1
maxLength: 1600
description: SMS body text, up to 1600 characters (longer bodies are rejected with 400). A number's own limit may be lower and is answered 422 body_too_long.
deliveryReport:
type: boolean
default: false
deprecated: true
description: 'Deprecated: best effort and ignored on most lines. Hosted SIM numbers return no carrier delivery report, so their messages end at `sent` and no `sms.send.delivered` event follows. Defaults to false.'
required:
- to
- body
MarkConversationReadResponse:
type: object
properties:
updated:
type: integer
minimum: 0
required:
- updated
MessageErrorResponse:
type: object
properties:
code:
$ref: '#/components/schemas/MessageErrorReason'
message:
type: string
required:
- code
- message
description: Messaging error envelope. `code` is the canonical discriminator (see `MessageErrorReason` for the code set).
NumberErrorResponse:
type: object
properties:
code:
$ref: '#/components/schemas/NumberErrorReason'
message:
type: string
details:
type: object
properties:
esimId:
type: string
format: uuid
required:
- esimId
required:
- code
- message
description: Phone-number error envelope. `code` is the canonical discriminator (see `NumberErrorReason` for the code set).
ConversationCursor:
type:
- object
- 'null'
properties:
lastOccurredAt:
type: string
format: date-time
lastMessageId:
type: string
format: uuid
required:
- lastOccurredAt
- lastMessageId
PublicMessageListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/PublicMessageRow'
pagination:
$ref: '#/components/schemas/Pagination'
required:
- items
- pagination
Pagination:
type: object
properties:
hasNext:
type: boolean
hasPrev:
type: boolean
page:
type: integer
minimum: 1
pageSize:
type: integer
minimum: 1
pages:
type: integer
minimum: 0
total:
type: integer
minimum: 0
required:
- hasNext
- hasPrev
- page
- pageSize
- pages
- total
ConversationLastMessage:
type: object
properties:
id:
type: string
format: uuid
direction:
type: string
enum:
- inbound
- outbound
status:
type: string
enum:
- received
- queued
- claimed
- sending
- sent
- sent_unconfirmed
- delivered
- failed
description: Message status. Outbound messages move queued → sending → sent, or end at failed. `sent` means the mobile network accepted the message and is the final success status. `delivered` and `sent_unconfirmed` are kept for compatibility; current lines return no carrier delivery report, so neither is emitted.
body:
type:
- string
- 'null'
occurredAt:
type: string
format: date-time
required:
- id
- direction
- status
- body
- occurredAt
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Opaque
description: Bearer token via Authorization header
x-refined-from:
- openapi.json
- mobilerun-ai-openapi.json
x-provenance:
method: harvested
publisher: Mobilerun
source: https://api.mobilerun.ai/v1/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)