Snapi SMS docs: Messaging

Learn how to send a text message with our SMS API.

POST Sending an SMS message

The https://api.snapisms.io/api/v1/send endpint accepts a POST request with the following request parameters:

Authentication

You must authenticate yourself.

Parameters

Parameter Value Description Required?
phone 447989787676 A phone number to send to. This must be in the E.164 format format, it shouldn't contain any spaces or letters, please ensure to add the "+" symbol at the beginning, it should be encoded as: %2B. The recipient should know that they're receiving this message. Yes
message Hello from Snapi SMS The content of your SMS message. This should be less than 160 characters. See our FAQs for more information. You cannot send abusive messages. Yes
sender_id Company name Message body will contain a sender id. By default this will be your account's first name. You can customise this globally for all messages in your account, or at the API level. This will account towards your overall character count. No
sender_optout_language Opt-out at domain.com Message body will contain a instructions on how to opt-out. This is sent on first contact with a recipient. By default we handle opt-out requests at snapisms.io/optout and also automatically handle STOP replies. You can customise this globally in your account, or at the API level. This will account towards your overall character count. No
enable_test_mode 0/1 If you would like to test your API key's sending capabilities without actually sending a message and consuming credits, you may specify 1 for this value on your request. We recommend doing this prior to sending a message via our SMS API to ensure it will send. No

Example

Here's a quick example of how to send a text message. We've enabled test mode in this example so that it doesn't consume credits. 

curl -X "POST" "https://api.snapisms.io/api/v1/send" \
              --header 'Authorization: Bearer 1|okLtigWRJac8XsMfsyWb04wTY6TsDgvtEm52oxPq' \
              -d "phone=%2B447900000000" \
              -d "message=Hello world" \
              -d "enable_test_mode=1"
Send message with Snapi SMS API example

Compliance

Request response

The /api/v1/send endpoint will respond with the following JSON data:

Key Value Description Always present?
success true/false Whether the message was successfully queued for sending. You should check the existence and value of this key in your application. No
message Successfully sent The message key will provide more details about the status of the request. Yes
message_id bc75bc01-06f1-4870-9a46-8fb4dab1d43d If a message was successfully queued, you'll see a message ID. No
credits_remaining 10 If a message was successfully queued, you'll get an update on the number of credits remaining. No
errors Array of errors and fields If there was a problem with the request, the fields and associated error messages will appear here. No

GET Checking SMS message delivery status

The https://api.snapisms.io/api/v1/status/:messageId endpint accepts a GET request where :messageId is the message ID of the message you'd like to check with the following request parameters:

Authentication

You can authenticate in one of two ways.

Parameters

Parameter Value Description Required?
disable_cache Boolean value, e.g: 1 or 0 By default, message status implement a 2 minute cache. This is to improve performance. If you'd like to fetch the latest status, apply this parameter to the request and set it to 1. No

Example

Here's a quick example of how to get the status of a message, you'd replace :messageId with your message ID, for example: https://api.snapisms.io/api/v1/status/bc75bc01-06f1-4870-9a46-8fb4dab1d43d

curl -X "GET" "https://api.snapisms.io/api/v1/status/bc75bc01-06f1-4870-9a46-8fb4dab1d43d" \
              --header 'Authorization: Bearer 1|okLtigWRJac8XsMfsyWb04wTY6TsDgvtEm52oxPq'
Check message status with Snapi SMS API example

Request response

The /api/v1/status/:messageId endpoint will respond with the following JSON data:

Key Value Description Always present?
success true/false Whether the status was retrieved successfully. You should check the existence and value of this key in your application. No
message Your message status The message key will provide more details about the status of the request. Yes
message_id bc75bc01-06f1-4870-9a46-8fb4dab1d43d The message ID that you're checking the status of. No
is_cached true/fakse If you're viewing a cached version of the message status this will be marked as true. If you opted to disable the cache, this will be marked as false. No
status sent The status of the message. Please also refer to our statuses below for their meanings. No

Possible returned status values

  • unassigned - Message is pending to be sent but is not currently sending and hasn't yet been attempted.
  • assigned - Message is about to attempt to send. Please ensure you have credits in your account.
  • sending - Queued for sending to carrier.
  • sent - Sent to carrier, but delivery receipt is not available.
  • delivered - Carrier has confirmed sending of this message.
  • failed - Message attempted to send, but failed during sending. This could be caused by a malformed message body. Please check your message contents.
  • dead - Unable to attempt to send message. Usually caused by insufficent credit balance in your account.