> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflecto.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Text a contact from the user's phone

> The `send_sms` MCP tool's backing endpoint. Sends `body` from the user's own phone to the contact behind `contact_handle` — a handle from `POST /v1/sms-agent/contact-queries`. **There is no way to send to a raw phone number**; anything that is not a phone-minted handle is a `400 invalid_contact_handle`.

Waits up to **30 seconds** for the phone to confirm, then returns `sent`, `failed` (with a `reason`) or `pending`. `pending` means not yet confirmed — the send is neither retried nor cancelled. **Idempotent on the handle:** calling again with the same handle returns the current state and never sends a second text. Handles are single-use, so a new text always needs a new lookup.

**Not end-to-end encrypted.** This is Reflecto's server-as-sender path: the request passes through Reflecto's server in memory, is encrypted to the phone with the server's key, and is never stored.

Sends share the phone's on-device limits (15/hour, 50/day, 5/hour to one recipient) and post a notification on the phone naming the recipient.



## OpenAPI

````yaml /openapi.yaml post /v1/sms-agent/sends
openapi: 3.1.0
info:
  title: Reflecto API
  version: 1.1.0
  description: >-
    The Reflecto public HTTP API lets you push notifications to your own paired

    devices — your Android phone and any browser extensions you've paired with
    it.

    Designed for the same job as Pushover or the old Pushbullet API: a single

    HTTPS call from a script, cron job, or webhook puts a notification on every

    screen you own.


    Authentication uses opaque prefixed bearer tokens (`rfk_live_…`) created and

    managed on your paired Android device — there are no email accounts, no

    passwords, no server-side user records beyond device pairing state. See the

    Authentication guide for the token lifecycle.


    The public-API surface is small on purpose: `POST /v1/send`, its

    capability-URL alias `POST /v1/send/{token}`, and a Pushover-compatible shim

    at `POST /v1/messages.json`. Mirroring traffic from your phone to your

    extension never reaches this surface — it stays end-to-end encrypted via the

    private `/v1/sync` SSE stream.


    See the Guides tab for the quickstart, authentication model, rate-limit

    contract, and encryption posture.
  contact:
    name: Reflecto
    url: https://github.com/reflectoapp/reflecto
  license:
    name: MIT
    url: https://github.com/reflectoapp/reflecto/blob/main/LICENSE
servers:
  - url: https://api.reflecto.dev
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Send
    description: Push notifications to one or all of your paired devices.
  - name: Pushover compatibility
    description: >-
      Drop-in replacement for `POST https://api.pushover.net/1/messages.json`.
      Field names, request shape, and response shape mirror Pushover's so
      existing senders can migrate by changing a single URL. See [Pushover
      compatibility guide](/guides/pushover-compatibility) for the full mapping.
paths:
  /v1/sms-agent/sends:
    post:
      tags:
        - SMS (assistant)
      summary: Text a contact from the user's phone
      description: >-
        The `send_sms` MCP tool's backing endpoint. Sends `body` from the user's
        own phone to the contact behind `contact_handle` — a handle from `POST
        /v1/sms-agent/contact-queries`. **There is no way to send to a raw phone
        number**; anything that is not a phone-minted handle is a `400
        invalid_contact_handle`.


        Waits up to **30 seconds** for the phone to confirm, then returns
        `sent`, `failed` (with a `reason`) or `pending`. `pending` means not yet
        confirmed — the send is neither retried nor cancelled. **Idempotent on
        the handle:** calling again with the same handle returns the current
        state and never sends a second text. Handles are single-use, so a new
        text always needs a new lookup.


        **Not end-to-end encrypted.** This is Reflecto's server-as-sender path:
        the request passes through Reflecto's server in memory, is encrypted to
        the phone with the server's key, and is never stored.


        Sends share the phone's on-device limits (15/hour, 50/day, 5/hour to one
        recipient) and post a notification on the phone naming the recipient.
      operationId: sendSmsToContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsAgentSendRequest'
            examples:
              send:
                value:
                  contact_handle: ch_q3V9xK2mP0aL7bN4cR1sTw
                  body: Running 15 minutes late for dinner
      responses:
        '200':
          description: The send's state when this call returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsAgentSendResponse'
              examples:
                sent:
                  value:
                    state: sent
                    recipient_label: Richa Sharma · Mobile
                failed:
                  value:
                    state: failed
                    reason: handle_expired
                pending:
                  value:
                    state: pending
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '426':
          $ref: '#/components/responses/UpgradeRequired'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '429':
          $ref: '#/components/responses/RateLimitedInteractions'
      security:
        - ConnectorOAuth: []
components:
  schemas:
    SmsAgentSendRequest:
      type: object
      properties:
        contact_handle:
          type: string
          description: >-
            A handle from `POST /v1/sms-agent/contact-queries`. There is no way
            to send to a raw phone number.
          example: ch_q3V9xK2mP0aL7bN4cR1sTw
        body:
          type: string
          description: The message text. 1–1600 characters.
          example: Running 15 minutes late for dinner
      required:
        - contact_handle
        - body
      additionalProperties: false
    SmsAgentSendResponse:
      type: object
      properties:
        state:
          type: string
          enum:
            - sent
            - failed
            - pending
          description: >-
            `sent` = the phone handed the SMS to the network. `failed` carries a
            `reason`. `pending` = not confirmed within 30 s; the send is neither
            retried nor cancelled, and calling again with the same handle
            returns the current state without sending again.
          example: sent
        reason:
          type: string
          enum:
            - disabled
            - rate_limited
            - handle_expired
            - no_sms_permission
            - no_service
            - send_error
            - phone_unreachable
          description: Present only when `state` is `failed`.
          example: handle_expired
        recipient_label:
          type: string
          description: >-
            `Name · Label` of the recipient, as the lookup returned it — when
            the phone reported it while this request was waiting. Never a
            number.
          example: Richa Sharma · Mobile
      required:
        - state
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: message_too_long
            message:
              type: string
              example: message must be ≤ 1500 bytes
            details:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
      required:
        - error
    SimpleErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        message:
          type: string
      required:
        - error
      description: >-
        Flat error shape used for auth failures — `invalid_token` carries only
        the stable code; `missing_token` adds a `message` hint pointing at the
        `Authorization: Bearer …` header. The `message` field is therefore
        optional.
  responses:
    BadRequest:
      description: Malformed payload or invalid field value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidPriority:
              value:
                error:
                  code: invalid_priority
                  message: priority must be one of min, low, default, high, urgent
            messageTooLong:
              value:
                error:
                  code: message_too_long
                  message: message must be ≤ 1500 bytes
                  details:
                    bytes: 1620
                    max: 1500
    Unauthorized:
      description: Missing, invalid, or revoked bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleErrorResponse'
          examples:
            missingToken:
              value:
                error: missing_token
                message: 'Authorization: Bearer rfk_live_… required'
            invalidToken:
              value:
                error: invalid_token
    Forbidden:
      description: Token exists but lacks scope for the requested action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            priorityCapped:
              value:
                error:
                  code: priority_capped
                  message: Token's priority_cap is 'default'; requested 'high'
    Conflict:
      description: The request conflicts with the current state of a resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            noPhoneDevice:
              summary: Owner has no paired phone to ask
              value:
                error:
                  code: no_phone_device
                  message: no_phone_device
    UpgradeRequired:
      description: >-
        The target phone's Reflecto app is too old to receive this — update
        Reflecto on the phone from the Google Play Store before this can be
        delivered. Nothing was sent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            phoneAppOutdated:
              value:
                error:
                  code: phone_app_outdated
                  message: >-
                    the paired phone's Reflecto app is too old to receive this —
                    update Reflecto on the phone from the Google Play Store
                    before this can be delivered; nothing was sent.
    PreconditionRequired:
      description: >-
        The paired phone hasn't reported its Reflecto app version, so support
        can't be confirmed — the user should update Reflecto and open it once.
        Nothing was sent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            phoneAppUnknown:
              value:
                error:
                  code: phone_app_unknown
                  message: >-
                    Reflecto can't confirm the user's phone supports texting for
                    an assistant. Ask the user to update Reflecto on their phone
                    and open it once, then try again; nothing was sent.
    RateLimitedInteractions:
      description: >-
        Rate limit or resource cap exceeded. For interaction creation this
        includes the 10-pending-per-owner cap; for ring and reminders, IP/token
        rate limits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimitExceeded:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit hit
            tooManyPending:
              summary: Owner already has 10 pending interactions
              value:
                error:
                  code: too_many_pending
                  message: too_many_pending
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rfk_live_…
      description: >-
        Opaque bearer token created on your paired Android phone. The format is
        `rfk_live_` followed by 32 URL-safe alphanumeric characters (≥160 bits
        of entropy). Test tokens use the `rfk_test_` prefix.
    ConnectorOAuth:
      type: http
      scheme: bearer
      description: >-
        OAuth 2.1 access token issued by Reflecto's authorization server to a
        connected AI assistant (the remote MCP connector flow). Must carry the
        `sms:send` scope, which is never granted to `rfk_live_` API tokens.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.