Navigation Navbar
shell

Introduction

Amplisend API allows users to send and receive SMS and run inbound and outbound activity reports.

Before you begin you need to have an Amplisend account and valid API keys.

All requests and responses make use of JSON formatted data and have have a content-type of application/json

Versioning

The Amplisend API makes use of versioning to ensure backwards compatability to all its users. The API version is made up of the release year and month (YYYY-MM).

The current verion of the API is 2020-02. All endpoints follow the same format of; https://api.amplisend.com/{api_version}/{uuid}/{api_endpoint}.

Authentication

To authorize, use this code:

curl "https://api.amplisend.com/2020-02/{uuid}"
  -H "Authorization: Basic {access_key}:{secret_token}"

Any request made to the Amplisend API requires valid API keys. You can generate new API keys at Amplisend > API Keys.

Your API key is made up of three parts; access key, secret token and UUID.

All three parts are required when making a request to the Amplisend API.

The access key and secret token are passed in the Authorization header and the UUID is passed in the URL.

Messages

Send Message

curl "https://api.amplisend.com/2020-02/{uuid}/messages/send-sms"
  -X POST
  -H "Authorization: Basic {access_key}:{secret_token}"
  -H "Content-Type: application/json"
  -d '{
    "messages": [
      {
        "destAddr": "+61491575254",
        "sourceAddr": "Santa",
        "message": "Hello Word, this is a sample SMS."
      }
    ]
  }'

200 Successful response

{
  "responseCode": 200,
  "responseMessage": "success",
  "createdTimestamp": "2020-02-01T00:00:00.000Z",
  "uuid": "733399b3-807d-46a3-be82-6dbf55dc295a",
  "messages": [
    {
      "destAddr": "+61491575254",
      "sourceAddr": "Santa",
      "message": "Hello Word, this is a sample SMS.",
      "messageId": "fd74bfe2-f0f3-487a-8cb3-c06de55a59ba",
      "encoding": "GSM_7BIT",
      "parts": 1
    }
  ]
}

402 Failed response - Insufficient balance

{
  "responseCode": 402,
  "responseMessage": "Insufficient balance",
  "uuid": "733399b3-807d-46a3-be82-6dbf55dc295a"
}

401 Failed response - Invalid parameters

{
  "responseCode": 401,
  "responseMessage": "Invalid \"PARAM\" parameter",
  "uuid": "733399b3-807d-46a3-be82-6dbf55dc295a"
}

Send an SMS

HTTP Request

POST https://api.amplisend.com/2020-02/{uuid}/messages/send-sms

Sample request with all parameters

"messages": [
  {
    "destAddr": "+61491575254",
    "sourceAddr": "Santa",
    "message": "Hello Word, this is a sample SMS.",
    "tags": {
      "id": 111,
      "user": "sam-abc-111",
      "foo": "bar"
    }
  },
  {
    "destAddr": "+61491570156",
    "sourceAddr": "Santa",
    "message": "Goodbye Word, sample SMS has been sent.",
    "tags": {
      "id": 222,
      "user": "jane-def-222",
      "foo": "bar"
    }
  }
],
"test": false

Body Parameters

Parameter Required Type Description
messages true message[] An array of up to 50 message objects.
test false boolean If set to true the SMS won't be sent and credits won't be deducted from the account.

Sample message object with all parameters

{
  "destAddr": "+61491575254",
  "sourceAddr": "Santa",
  "message": "Hello Word, this is a sample SMS.",
  "tags": {
    "id": 123456,
    "user": "sam-abc-123",
    "foo": "bar"
  }
}

Message Object

Parameter Required Type Description
destAddr true E.164 formatted mobile number A valid international mobile number. Must contain + symbol and valid country code.
sourceAddr false E.164 formatted number or string The source address that the message should come from. This can be an alphanumberic string of up to 11 characters, or a numberic value of up to 16 numbers.
message true string Message contents of up to 1,600 characters.
tags false tag An object of up to 10 key-value pairs.
webhook false webhook An object containing details of where message related events are sent.

If no sourceAddr is specified the message will come from one of Amplisends local Australian mobile numbers. This will allow two-way functionality and give you the ability to receive replies to your message.

If no webhook is specified and there are account level event webhooks set then all events are sent to the account level settings.

Sample tag object

{
  "id": 123456,
  "user": "sam-abc-123",
  "foo": "bar"
}

Tag Object

Parameter Required Type Description
[key: string] true string Key of up to 50 characters
value true string or integer Value of up to 100 characeters

Webhook Object

Parameter Required Type Description
url true string URL where message related events should be sent.
mo false boolean When set to true any replies to your message will be sent to the above URL.
dlr false boolean When set to true any delivery receipts to your message will be sent to the above URL.

Web Hooks

Signatures

hash_hmac 'sha256' requestBody signature

All webhooks sent by Amplisend contain a digital signature which can be used to verify their authenticity. The signature is a HMAC SHA256 key which is generated with the webhook client secret along with the data sent in the request.

The signature can be found in the x-amplisend-signature header, compare it against the HMAC digest and if they match you can confirm the webhook was sent by Amplisend.

Inbound Messages

Inbound messages are pushed via webhook to your specified URL.

URLs can be set in the platform by updating the options at Amplisend > Webhooks.

A POST request with a Content-Type: application/json will be made to your webook URL. A valid 200 HTTP status is expected, any other response will trigger a retry event.

Sample inbound message posted to a webhook

{
  "createdTimestamp": "2020-03-10T09:35:47.238Z",
  "messageId": "18c840dc-a04c-4e8a-925e-409b07e7ce84",
  "sourceAddr": "+61491571266",
  "destAddr": "+61491575789",
  "message": "Hello World, foo bar",
  "tags": {
    "id": 123456,
    "user": "sam-abc-123",
    "foo": "bar"
  },
  "optOut": true,
}
Property Description
createdTimestamp ISO formatted timestamp.
messageId Unique message ID from the originating message.
sourceAddr The mobile phone number sending the inbound message (The customer).
destAddr The Amplisend number that received the message.
message The contents of the inbound message.
tags Optional The tags supplied in the originating message.
optOut Optional If the reply triggers an opt out this property will be included.

Delivery Receipts

Delivery receipts are pushed via webhook to your specified URL.

URLs can be set in the platform by updating the options at Amplisend > Webhooks.

A POST request with a Content-Type: application/json will be made to your webook URL. A valid 200 HTTP status is expected, any other response will trigger a retry event.

Sample delivery receipt posted to a webhook

{
  "createdTimestamp": "2020-03-10T09:35:47.238Z",
  "messageId": "18c840dc-a04c-4e8a-925e-409b07e7ce84",
  "status": "DELIVERED",
  "tags": {
    "id": 123456,
    "user": "sam-abc-123",
    "foo": "bar"
  }
}
Property Description
createdTimestamp ISO formatted timestamp.
messageId Unique message ID from the originating message.
status Status of the message
tags Optional The tags supplied in the originating message.

Amplisend follows the SMPP delivery receipt protocol with an additional status of OPTOUT.

Status Final State Description
ENROUTE false SMS has been accepted and has been pushed to the upstream carrier.
EXPIRED true SMS has given up trying to send and won't be delivered to the phone number.
UNDELIVERABLE true SMS has failed to deliver and won't continue to attempt delivery.
DELETED true The message has been cancelled or deleted by the carrier and won't be delivered to the phone number.
DELIVERED true The message has been delivered to the phone number.
OPTOUT true The phone number is part of your opt out list and delivery won't be attempted.
shell