openapi: 3.2.0
info:
  title: Route Mobile SMS Integrations API
  description: 'Complete API reference for Route Mobile''s SMS platform. Covers message submission,

    OTP, account management, and third-party platform integrations.


    ## Authentication


    Most APIs authenticate via `username` and `password` query parameters.

    Third-party integration APIs (Moengage, Webengage) use a static `Authorization`

    header token provided by Route Mobile.


    ## Base URLs


    | URL | Description |

    |-----|-------------|

    | `https://api.rmlconnect.net` | Secured HTTPS (port 443) — recommended |

    | `https://api.rmlconnect.net:8443` | Secured HTTPS (port 8443) |

    | `http://api.rmlconnect.net` | Non-secured HTTP — legacy only |

    | `https://client.rmlconnect.net` | Client portal — coverage map only |


    ## Platform Response Codes


    SMS submission APIs return a plain text response with a platform status code prefix.


    | Code | Meaning |

    |------|---------|

    | 1701 | Success — `1701\|<CELL_NO>\|<MESSAGE_ID>` |

    | 1702 | Invalid URL / missing or blank parameter |

    | 1703 | Invalid username or password |

    | 1704 | Invalid value in `type` field |

    | 1705 | Invalid message |

    | 1706 | Invalid destination |

    | 1707 | Invalid source (Sender ID) |

    | 1708 | Invalid value in `dlr` field |

    | 1709 | User validation failed |

    | 1710 | Internal error |

    | 1025 | Insufficient credit |

    | 1715 | Response timeout |


    > **Retry Policy:** Do NOT retry for any error code except `1709`.

    > For `1715` specifically, do not re-submit the same message.

    '
  version: 1.0.0
  contact:
    name: Route Mobile Support
    email: support@routemobile.com
    url: https://developers.routemobile.com/
  x-readme:
    samples-languages:
    - curl
    - python
    - node
    - java
    - php
servers:
- url: https://api.rmlconnect.net
  description: SGN Secured (HTTPS - port 443) — recommended
- url: https://api.rmlconnect.net:8443
  description: SGN Secured (HTTPS - port 8443)
- url: http://api.rmlconnect.net
  description: SGN Non-secured (HTTP) — legacy only
- url: https://client.rmlconnect.net
  description: Client Portal — coverage map only
tags:
- name: Integrations
  description: APIs for third-party platform integrations.
paths:
  /bulksms/custommsgsubmit:
    post:
      tags:
      - Integrations
      summary: Moengage Integration
      description: 'Endpoint for integrating the SGN SMS platform with the Moengage customer

        engagement platform. Authentication is via a static `Authorization` header

        token provided by Route Mobile.


        > **Note:** This endpoint uses HTTP POST but accepts parameters as query strings

        > rather than a JSON body. This is by design for Moengage platform compatibility —

        > ensure your integration passes parameters in the URL query string, not the request body.

        '
      operationId: submitMoengageSms
      parameters:
      - name: recipient
        in: query
        required: true
        description: Destination MSISDN in international format (without +).
        schema:
          type: string
          example: '919999999999'
      - name: reply_to
        in: query
        required: true
        description: 'Sender ID / source address.

          - Max **18 characters** if numeric only

          - Max **11 characters** if alphanumeric

          '
        schema:
          type: string
      - name: messageBody
        in: query
        required: true
        description: SMS content to be delivered (URL-encoded).
        schema:
          type: string
          example: Moesms_message
      security:
      - AuthorizationToken: []
      responses:
        '200':
          description: Submission accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoengageResponse'
              examples:
                Success:
                  value:
                    success: 'true'
                    messageid: e71516a1-2f68-4b12-aa62-62365d7b930a
                    mobileno: '919999999999'
                    error: '1701'
                Failure:
                  value:
                    success: 'false'
                    messageid: ''
                    mobileno: '919999999999'
                    error: '1706'
        '401':
          description: Invalid Authorization header.
        '500':
          description: Internal server error. Please contact support if this persists.
  /bulksms2346/sendjsonsms:
    post:
      tags:
      - Integrations
      summary: Webengage Integration
      description: 'Endpoint for integrating the SGN SMS platform with the Webengage customer

        engagement platform. Authentication is via a static `Authorization` header

        token provided by Route Mobile.

        '
      operationId: submitWebengageSms
      security:
      - AuthorizationToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebengageRequest'
            example:
              version: '1.0'
              smsData:
                toNumber: '919999999999'
                fromNumber: TESTSM
                body: test message
              metadata:
                campaignType: PROMOTIONAL
                timestamp: 2024-03-19T19:33:13+0000
                messageId: abcde-1234-5678-90ab-cdef12345678
      responses:
        '200':
          description: Submission accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebengageResponse'
              examples:
                Success:
                  value:
                    status: sms_accepted
        '400':
          description: Invalid payload.
        '401':
          description: Invalid Authorization header.
        '500':
          description: Internal server error. Please contact support if this persists.
components:
  schemas:
    WebengageRequest:
      type: object
      required:
      - version
      - smsData
      - metadata
      properties:
        version:
          type: string
          description: API contract version.
          example: '1.0'
        smsData:
          $ref: '#/components/schemas/SmsData'
        metadata:
          $ref: '#/components/schemas/Metadata'
    Metadata:
      type: object
      required:
      - campaignType
      - timestamp
      - messageId
      properties:
        campaignType:
          type: string
          description: Campaign category.
          enum:
          - PROMOTIONAL
          - TRANSACTIONAL
          - OTP
          - SERVICE
        timestamp:
          type: string
          description: ISO-8601 timestamp of the request.
        messageId:
          type: string
          description: Unique message ID generated by Webengage.
    MoengageResponse:
      type: object
      properties:
        success:
          type: string
          description: '"true" if accepted, "false" otherwise.'
        messageid:
          type: string
          description: Unique message ID assigned by the platform.
        mobileno:
          type: string
          description: Destination MSISDN.
        error:
          type: string
          description: 'Platform status code.

            - `1701` — Success

            - `1702` — Invalid URL / missing parameter

            - `1703` — Invalid username or password

            - `1706` — Invalid destination

            - `1707` — Invalid source (Sender ID)

            - `1710` — Internal error

            - `1025` — Insufficient credit

            '
    WebengageResponse:
      type: object
      properties:
        status:
          type: string
          description: Acceptance status returned by the platform.
          example: sms_accepted
    SmsData:
      type: object
      required:
      - toNumber
      - fromNumber
      - body
      properties:
        toNumber:
          type: string
          description: Destination MSISDN in international format (without +).
        fromNumber:
          type: string
          description: Sender ID / source address.
        body:
          type: string
          description: SMS content.
  securitySchemes:
    AuthorizationToken:
      type: apiKey
      in: header
      name: Authorization
      description: Static authorization token provided by Route Mobile. Used for Moengage and Webengage integrations.