Mobilerun Messages API

The Messages API from Mobilerun — 5 operation(s) for messages.

GitHub OpenAPI

Operations 5

GET /numbers/messages List the caller's own SMS inbox/outbox messages #
GET /numbers/messages/conversations List the caller's own SMS conversations, one row per thread #
POST /numbers/messages/conversations/read Mark a conversation's inbound messages read up to a cursor #
GET /numbers/messages/{id} Get one of the caller's SMS messages #
POST /numbers/phones/{id}/messages Send an SMS from a number #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/mobilerun-ai:mobilerun-ai-messages-api"
All apis
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.

Get an API 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 Specification

mobilerun-ai-messages-api-openapi.yml Raw ↑
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)