Overview

API Interface: HTTPS
Resource: Send and Receive MMS
Host: mmsc.aerialink.net port 2525
URI: /v4/messages
Methods: POST
Response Schemas: JSON (default), XML

An application programming interface for connecting external applications, systems, and devices with the Aerialink Service Gateway for the purpose of sending and/or receiving SMS (Text Messages), MMS (Multimedia Messages), or Data (Binary) content between an application service and a mobile wireless handset or device operating on any approved wireless carrier. This specific API covers MMS messages only.

Response Schema

Aerialink supports both JSON and XML response schemas, however the default response schema is JSON. If you wish to receive your response schema in XML or explicitly set the response schema to JSON, follow these examples as you construct your complete request URL.

/messages
(defaults to JSON automatically)

/messages.json
(explicitly sets the response to a JSON schema, same as default)

/messages.xml
(sets the response to an XML schema)

Method [POST] : Sending One Attachment

This method sends an MMS message from your application to the Aerialink Gateway for ultimate delivery to the destination number. The request is initiated by your application.

Note that the below instructions are for sending a single attachment. To send multiple attachments, you will need to use MM4. The specification for this protocol can be found here.

Request

The available request parameters for this resource and method are listed below and should be sent form-post.

Required Parameters

• source [string(15)]
  The source code for the message. This must match to one of your codes associated with your connection.

• destination [string(15)]
  The destination number that you want to send the MMS message to. The recommendation for US based numbers is the 11 digit format: “13105551212”.

• messageText [string(160)]
  The MMS message text that you are sending to the end user handset device. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.

• mmsURL [string(160)]
  The URL for the MMS image which is to be sent to the mobile user. This URL must be publicly accessible.

Optional Parameters

• destinationFormat [integer]
  Defaults to 0 for “friendly format” which is the default. If this parameter is passed with a value of 1 then Aerialink will expect the destination number in “international format” with the country code (ex. “xXXXxxxXXXX”). This is required for any international messaging.

• registeredDelivery [integer]
  Defaults to 0. If set to 1, this will request a delivery receipt from the carrier which will be delivered to the URL that you specify in your account configuration.

• programID [string(25)]
  This parameter is required for some short codes and is handled by Aerialink on the backend, where we configure it to the code and pass it to the carrier. Therefore, it does not need to be included in the calls sent by customers to Aerialink.

• mmsSubject [string(40)]
  This parameter is the “subject” text of the MMS you are sending to the end-user device. This is limited to the general standard of forty characters, but character limit may be less depending upon the use of case and configuration or carrier limitation.

Response (Synchronous)

Response Properties

The parameters or elements returned in the response to an API request.

• version : The requested version of the resource
• resource : The requested resource name
• method : The method for the request. This will always be one of the following; GET, POST, UPDATE, DELETE
• type : The request type; Synchronous or Asynchronous
• transactionGUID : The globally unique transaction ID for the message
• destination : Operating company directory number

Response Schema

JSON Format(default schema)

{
  "aerialink": {
    "version": "v4",
    "resource": "messages",
    "method": "post",
    "type": "synchronous",
    "transactions": [
      {
        "transaction": {
          "transactionGUID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "destination": "12223334444"
        }
      }
    ]
  }
}

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<aerialink>
 <version>v4</version>
 <resource>messages</resource>
 <method>post</method>
 <type>synchronous</type>
 <transactions>
  <transaction>
  <transactionGUID>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</transactionGUID>
  <destination>12223334444</destination>
  </transaction>
 </transactions>
</aerialink>

Python Format

import urllib
import urllib2
import base64
from pprint import pprint

#setup api creds
base64string = base64.encodestring('%s:%s' % ('[YOUR SID]', '[YOUR TOKEN]')).replace('\n', '')

#Aerialink POST
url = 'https://apix.aerialink.net/v4/messages'
values = {'source' : '[YOUR SMS NUMBER]',
          'destination' : '[MOBILE NUMBER]',
          'messageText' : 'Aerialink',
          'mmsURL' : '[YOUR IMAGE URL]' }

data = urllib.urlencode(values)
req = urllib2.Request(url, data)
req.add_header("Authorization", "Basic %s" % base64string)
response = urllib2.urlopen(req)
the_page = response.read()

#output the response
pprint(the_page)

Method [POST] : Send Multiple Attachments

To begin sending MM4, one must send traffic to our SMTP server mmsc.aerialink.net on port 587.
Please see the following example to send MMS via MM4 using Python3:

Request

import smtplib, ssl  
from email import encoders  
from email.mime.base import MIMEBase  
from email.mime.text import MIMEText  
from email.mime.multipart import MIMEMultipart  

sender = "+1234567890@mmsc.aerialink.net"  
receiver = "+1987654321@mmsc.aerialink.net"  
user = "[api-key]"  
password = "[api-secret]"  

msg = MIMEMultipart()  
msg["Subject"] = "mm4"  
msg["From"] = sender  
msg["To"] = receiver  
msg["Body"] = "Test"  
msg.attach(MIMEText(msg["Body"], "plain"))  

file = "[mms-attachment]"  

with open(file, "rb") as attachment:  
    image = MIMEBase("image", "octet-stream")  
    image.set_payload(attachment.read())  

encoders.encode_base64(image)  

image.add_header("Content-Disposition","attachment; filename = 'file'")  
msg.attach(image)  
email = msg.as_string()  
context = ssl.create_default_context()  

with smtplib.SMTP_SSL("mmsc.aerialink.net:587") as server:  
    server.login(user, password)  
    server.sendmail(sender, receiver, email)  

To enable DLR for MM4 messages please use the header ‘X-Mms-Delivery-Report’, in our above example we will add the line:

msg['X-Mms-Delivery-Report'] = 'Yes'  

To add participants to the MMS (Group Messaging), list the intended recipients in the receiver field, using our current example the receiver variable will look as follows:

receiver = "+1987654321@mmsc.aerialink.net, +1111111111@mmsc.aerialink.net, +2222222222@mmsc.aerialink.net, +3333333333@mmsc.aerialink.net"  

Please note that by adding additional recipients we will have to use the split function when calling sendmail:

with smtplib.SMTP_SSL(“mmsc.aerialink.net:587”) as server:
server.login(user, password)
server.sendmail(sender, receiver.split(‘,’), email)

To receive a transaction GUID for your MT messages, one will have to edit the SMTP module ‘stmplib’ to reflect the following where the line highlighted in yellow was inserted:

The sendmail function will now return a variable of list type which contains the status code of the message, and a transaction GUID for each recipient.

A few items to note:

• Source and destination numbers must follow this convention: “+[code]@mmsc.aerialink.net”
• The credentials used will be the API key/secret pair for the connection where the code is provisioned on.
• Ensure that the originating IP is whitelisted in the accounts firewall rules

Method [POST] : Receiving an MMS

This method is used by Aerialink to deliver a message from an end-user device to your application. The request is initiated by Aerialink

Request

Send the following request parameters form-post via an HTTP POST to the URL that you have defined in your connection/route. This can be configured or modified within the Aerialink Platform Portal.

Parameters

• transactionGUID [string(36)]
  The globally unique transaction ID for the message.

• connectionGUID [string(36)]
  The globally unique identifier for the Aerialink network connection in your account which processed the transaction.

• source [string(15)]
  The source address for the message. This is the end user mobile phone which sent you the message.

• sourceCountry [string(255)]
  The registered country name for the number.

• sourceCountryCode [integer]
  The associated country code for the number.

• sourceCountryAbbreviation [string(2)]
  The two-letter country abbreviation (ISO 3166-1 alpha-2)

• destination [string(15)]
  The destination number that the end user sent the message to. This will match with a Short/Long Code configured on your account.

• messageText [string(160)]
  The MMS message text that the end user sent to your Short/Long Code. This is limited to the general standard of 160 characters unless concatenation is enabled on your account. In some cases your character limit may be less depending on your specific use case and configuration or a carrier limitation.

• mmsURL [string(160)]
  The URL for the MMS image which is received from the mobile user. This URL must be publicly accessible.

• mmsSubject [string(40)]
  This parameter is the “subject” text of the MMS received from the end-user device. This is limited to the general standard of forty characters, but character limit may be less depending upon the use of case and configuration or carrier limitation.

• concatenatedMessage [string(5)]
  true/false

• attachments
  Returns information about the multimedia content “attached” to the message.

Optional Parameters

• sourceNational [string(15]
  The source address for the message in national format, excluding the country code. This is the end user mobile phone which sent you the message.

• udh [string(25)]
  Variable length defined inside the UDH itself

• concatenatedMessageReference [string(5)]
  string up to five characters

• concatenatedMessageSegments [integer]

• concatenatedMessageSegmentNumber [integer]

Response (Synchronous or Aynchronous)

Aerialink will return an HTTP(s) status code in the 200 range upon a successful request along with the following response details. The 200 range could be any of the following values (200, 201, 202, 203, 204, 205, or 206) but in most all cases will be 200. If you do not receive one of these status codes in the response from us, your application should retry the HTTP(s) request at a later date or refer to the specific HTTP status code for more detail.