Send SMS

v1.30. The sms service creates a service that can send mobile messages via APIs. Multiple SMS APIs are supported:

Amazon SNS

Here is a sample config for Amazon SNS:

    type: amazonsns
    aws_access_key_id: ...
    aws_secret_access_key: ...
    region_name: ap-southeast-1
    smstype: Transactional

To set up SNS:

The smstype parameter for Amazon SNS can be either



Here is a sample config for Exotel:

    type: exotel
    sid: ...            # Account Sid
    key: ...            # API KEY
    token: ...          # API TOKEN
    domain: ...         # Optional. Defaults to
    priority: high      # Optional. Can be high or normal. Defaults to high

To set up Exotel:

  1. Create a developer account at
  2. Visit Settings > Sender ID. Click Change icon. Add a 6 character string. Await approval by the Exotel team.
  3. Visit Settings > SMS Templates. Add a transactional template. For example: OTP requested by %s with mobile %s.. Request approval.
  4. Visit Settings > API Settings. Add the following in gramex.yaml.
    • sid: Account Sid
    • key: API KEY
    • token: API TOKEN


  1. The mobile number can be in any format. +91 9741 552 552, 09741552552, 9741-552-552 are the same.
  2. Messages that do not conform to an SMS template may show an error message No SMS SenderId found for Account=[...], From=[...]
  3. Use %s for numbers as well as text, despite the Exotel documentation
  4. Do not end with a variable, e.g. mobile %s is invalid. But mobile %s. with a period (.) at the end is valid.

See the Exotel documentation at


Twilio SMS is on the roadmap.

Send SMS

To send an SMS programmatically – for example, inside a FunctionHandler or in a scheduler:

import gramex
notifier = gramex.service.sms['amazon']     # Available only if Gramex is running
# Or, to construct the Notifier when using Gramex as a library, use:
# from import AmazonSNS
# notifier = AmazonSNS(aws_access_key_id, aws_access_secret_key, region_name)
result = notifier.send(
    to='+919741552552',         # International mobile number
    subject='Message to send',  # Text message to send
    sender='Gramex',            # Optional sender identifier

The result has the API response which contains additional information about the SMS. To fetch its delivery status, use:

status = notifier.status(result)    # Not available for Amazon SNS

This returns the API response for the delivery status.

Here is a sample form to send messages:

Note: Depending on the geography, the “Sender” field may not be sent. In India, it is not. The sender is replaced with “HP-Notice” or similar messages. In Singapore, the Sender field is used as-is.