MessageMedia REST API Documentation

Summary

Title MessageMedia REST API
Description Australia's Leading Messaging Solutions for Business and Enterprise.
Version 1.0.0
Host api.messagemedia.com
Scheme
https
Base Path
/v1
Produces
application/json

Security

Authorization

Signing an API request

Every request requires an Authorization header in the following format:

Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="date, content-md5", signature="<SIGNATURE>"

To create this header:

  1. Add a Date header to the request using the current date time in RFC7231 Section 7.1.1.2 format
  2. Add a header called Content-MD5 where the value of this header is an MD5 hash of the request body
  3. Create a signing string by concatenating the Date header, the Content-MD5 header and the request line with line breaks:
    date: Sat, 30 Jul 2016 05:13:23 GMT\ncontent-md5: 10fd4feab20d38432480c07301e49616\nPOST /v1/messages HTTP/1.1

  4. Create a SHA1 HMAC hash of the signing string using the secret key HMAC-SHA1(signing string)
  5. Base64 encode the HMAC hash and include it as the signature in the Authorization header
Example request

Putting this all together, an example POST request would appear as follows:

POST /v1/messages HTTP/1.1
  Host: api.messagemedia.com
  Accept: application/json
  Content-Type: application/json
  Date: Sat, 30 Jul 2016 05:18:52 GMT
  Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="date content-md5 request-line", signature="Ia4G5lkhH/3NDYpix+8ZHUnp6bA="
  Content-MD5: 10fd4feab20d38432480c07301e49616
  Content-Length: 201

  {
      "messages": [
          {
              "content": "Hello World",
              "delivery_report": false,
              "destination_number": "+61401760575",
              "format": "SMS"
          }
      ]
  }

Parameters

Name
In
Description
Authorization
header Authorization header containing API key, algorithm, list of headers used to sign request and the request signature.
Content-MD5
header An MD5 hash of the request body.
Date
header The date and time at which the message was originated, as per [RFC7231 Section 7.1.1.2](http://tools.ietf.org/html/rfc7231#section-7.1.1.2).

Endpoints

Path
Method
Summary
/messages

POST

Send one or more SMS or text to voice messages.
/messages/{messageId}

GET

Get details of a submitted message.
/messages/{messageId}

PUT

Update the status of a submitted message.
/replies

GET

Check for unconfirmed replies.
/replies/confirmed

POST

Confirm the receipt of replies.
/delivery_reports

GET

Check for unconfirmed reports.
/delivery_reports/confirmed

POST

Confirm the receipt of delivery reports.
/reporting/delivery_reports

GET

Get a list of delivered reports received.
/reporting/received_messages

GET

Get a list of received messages.
/reporting/sent_messages

GET

Get a list of sent messages.

Messages

POST /messages

Summary

Send one or more SMS or text to voice messages.

Description

Submit one or more (up to 100 per request) SMS or text to voice messages to be sent to the destination address.

  • A callback URL can be included with each message to which MO and DR notifications will be pushed to via a HTTP POST request.
  • The content of the message can be a unicode string, up to 5000 characters long
  • A delivery report can be be requested with the message which will be pushed to a HTTP endpoint if specified, or available via the Check Reports endpoint.
  • The destination number should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164
  • The format specifies which format the message will be sent as, SMS or VOICE
  • If specified the source number included in the request will be shown as the source number for the message, this feature is not enabled by default, please contact MessageMedia for more information.
  • If a source number is specified, the type of source number may also be specified.
  • The message will be scheduled to be delivered in the future if the scheduled parameter is specified.
  • A message expiry timestamp can be provided, if the message is not delivered by this time, it will be discarded.
  • Metadata can be included with the message. Up to 5 key value pair strings can be included with each message. This metadata will be available in delivery reports and replies.

Parameters

Name
Description
Location
Required
Schema
messages

A list of messages to be sent.

body Yes
Type
object
Required messages
JSON Schema  Expand source
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

202

Messages were accepted for processing. NewMessages
Example  Expand source

400

Message request was invalid ErrorDetails

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error
GET /messages/{messageId}

Summary

Get details of a submitted message.

Description

Get the status and details of a previously submitted message

Parameters

Name
Description
Location
Required
Schema
messageId

Unique identifier representing message that has been submitted

path Yes
string (uuid)
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

200

The submitted message including the status of the message SubmittedMessage

404

Message not found Error

500

Unexpected error Error
PUT /messages/{messageId}

Summary

Update the status of a submitted message.

Description

Update the status of a scheduled message to cancelled to prevent the message from being sent

Parameters

Name
Description
Location
Required
Schema
messageId

Unique identifier representing message to be updated.

path Yes
string (uuid)
status

New status for the message.

body Yes
Type
object
Required status
JSON Schema  Expand source
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

200

Message status updated successfully Empty

400

Request body is invalid, or the status of the message is not scheduled Error

403

Invalid credentials, or attempting to use unauthorised account Error

404

Message not found Error

500

Unexpected error Error

Replies

GET /replies

Summary

Check for unconfirmed replies.

Description

Return the first 100 reply messages that have been received and haven't been confirmed using the confirm replies endpoint.

Parameters

Name
Description
Location
Required
Schema
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

200

Unconfirmed replies Replies

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error
POST /replies/confirmed

Summary

Confirm the receipt of replies.

Description

Update the specified replies as confirmed, confirmed replies will no longer be returned in check replies requests.

Parameters

Name
Description
Location
Required
Schema
reply_id

A list of reply IDs to mark as confirmed.

body Yes
Type
object
Required reply_ids
JSON Schema  Expand source
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

202

Requested replies will be marked as confirmed. Empty

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error

Deliveryreports

GET /delivery_reports

Summary

Check for unconfirmed reports.

Description

Returns the first 100 delivery reports that have been received and haven't been confirmed using the confirm reports endpoint.

Parameters

Name
Description
Location
Required
Schema
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

200

Unconfirmed reports. Reports

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error
POST /delivery_reports/confirmed

Summary

Confirm the receipt of delivery reports.

Description

Update the specified delivery reports as confirmed, confirmed delivery reports will no longer be returned in check delivery reports requests.

Parameters

Name
Description
Location
Required
Schema
delivery_report_id

A list of delivery report IDs to mark as confirmed.

body Yes
Type
object
Required delivery_report_ids
JSON Schema  Expand source
Account

The account to use for this request. This account will be used for the request instead of the account assigned to the API key used to sign the request, allowing one API key to be used to perform requests on behalf of other accounts.

header No
string (string)

Responses

Code
Description
Schema
Example

202

Requested delivery reports will be marked as confirmed. Empty

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error

Responses

Code
Description
Schema
Example

200

A list of all messages sent in the specified time window. DeliveryReports

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error
GET /reporting/received_messages

Summary

Get a list of received messages.

Description

Returns a detailed list of all message received during the specified time.

Parameters

Name
Description
Location
Required
Schema
account

Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub accounts.

query No
string
action

Filter results by the action that was invoked for this message.

query No
string
destination_address_country

Fitler results by destination address country.

query No
string (ISO 3166-1 alpha-2)
destination_address

Fitler results by destination address.

query No
string
end_date

End date time for report window.

query Yes
string (date-time)
message_format

Fitler results by message format.

query No
string
metadata_key

Fitler results for messages that include a metadata key.

query No
string
metadata_value

Fitler results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.

query No
string
sort_by

Field to sort results set by.

query No
string
sort_direction

Order to sort results by.

query No
string
source_address_country

Fitler results by source address country.

query No
string (ISO 3166-1 alpha-2)
source_address

Fitler results by source address.

query No
string
start_date

Start date time for report window.

query Yes
string (date-time)

Responses

Code
Description
Schema
Example

200

A list of all messages received in the specified time window. ReceivedMessages

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error
GET /reporting/sent_messages

Summary

Get a list of sent messages.

Description

Returns a detailed list of all message sent during the specified time.

Parameters

Name
Description
Location
Required
Schema
account

Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub accounts.

query No
string
delivery_report

Filter results by delivery report.

query No
boolean
destination_address_country

Fitler results by destination address country.

query No
string (ISO 3166-1 alpha-2)
destination_address

Fitler results by destination address.

query No
string
end_date

End date time for report window.

query Yes
string (date-time)
message_format

Fitler results by message format.

query No
string
metadata_key

Fitler results for messages that include a metadata key.

query No
string
metadata_value

Fitler results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.

query No
string
status_code

Fitler results by message status code.

query No
string
status

Fitler results by message status.

query No
string
sort_by

Field to sort results set by.

query No
string
sort_direction

Order to sort results by.

query No
string
source_address_country

Fitler results by source address country.

query No
string (ISO 3166-1 alpha-2)
source_address

Fitler results by source address.

query No
string
start_date

Start date time for report window.

query Yes
string (date-time)

Responses

Code
Description
Schema
Example

200

A list of all messages sent in the specified time window. SentMessages

403

Invalid credentials, or attempting to use unauthorised account Error

500

Unexpected error Error

Schema Definitions

DeliveryReport

Description

A delivery report that has been received indicating the status of a sent message.

Type
object

Properties

Name
Description
Type
Default
account

Account associated with this delivery report

string
destination_address

Address this delivery report was delivered to. This is the source address of the sent message that this delivery report is in response to.

string
destination_address_country

Country associated with the destination address.

string (ISO-3066 alpha-2)
format

Format of message.

string
SMS
id

Unique identifier for this delivery report.

string (uuid)
in_response_to

ID of the sent message that this delivery report is in response to.

string (uuid)
metadata

This is the metadata associated with the sent message.

object
source_address

Address this delivery report was received from. This is the destination address of the sent message that this delivery report is in response to.

string
source_address_country

Country associated with the source address.

string (ISO-3066 alpha-2)
status

Status of the message.

string
status_code

Status code of the message.

string
timestamp

Date time at which this delivery report was received.

string (date-time)
JSON Schema  Expand source
DeliveryReports
Type
object

Properties

Name
Description
Type
Default
page

The current page of results.

integer
page_size

The amount of results returned per page.

integer
total_count

The total number of results in the results set.

integer
page_count

The total number of pages in the results set.

integer
next_uri

Link to the next page of results.

string
previous_uri

Link to the previous page of results.

string
data

List of delivery reports

array (DeliveryReport)
JSON Schema  Expand source
Error
Type
object

Properties

Name
Description
Type
Default
message
string
JSON Schema  Expand source
ErrorDetails
Type
object

Properties

Name
Description
Type
Default
message
string
details
array (string)
JSON Schema  Expand source
MessageFormat

Description

Format of message.

Type
string
Enum
SMS, VOICE
Default SMS
JSON Schema  Expand source
MessageMetadata

Description

Metadata for the message specified as a set of key value pairs, each key must be no longer than 100 characters, each value must be no longer than 256 characters.

{
   "myKey": "myValue",
   "anotherKey": "anotherValue"
}
Type
object
MaxProperties 5
JSON Schema  Expand source
MessageStatus

Description

Status of the message.

Type
string
Enum
queued, processing, processed, scheduled, cancelled, enroute, held, submitted, delivered, expired, rejected
JSON Schema  Expand source
MessageStatusCode

Description

Status code of the message.

Type
string
JSON Schema  Expand source
NewMessage
Type
object

Properties

Name
Description
Type
Default
callback_url

URL replies and delivery reports to this message will be pushed to.

string (url)
content

Content of message.

string
destination_number

Destination number of the message.

string
delivery_report
boolean
format

Format of message.

string
SMS
message_expiry_timestamp

Date time after which the message is considered expired in ISO8601 format.

string (date-time)
metadata

Metadata for the message specified as a set of key value pairs, each key must be no longer than 100 characters, each value must be no longer than 256 characters.

{
   "myKey": "myValue",
   "anotherKey": "anotherValue"
}
object
scheduled

Date time at which the message is scheduled for in ISO8601 format.

string (date-time)
source_address
string
source_address_type

Type of source address specified.

string
JSON Schema  Expand source
NewMessages
Type
object

Properties

Name
Description
Type
Default
messages
array (NewMessage)
JSON Schema  Expand source
Pagination
Type
object

Properties

Name
Description
Type
Default
page

The current page of results.

integer
page_size

The amount of results returned per page.

integer
total_count

The total number of results in the results set.

integer
page_count

The total number of pages in the results set.

integer
next_uri

Link to the next page of results.

string
previous_uri

Link to the previous page of results.

string
JSON Schema  Expand source
Replies
Type
object
Required replies

Properties

Name
Description
Type
Default
replies

The oldest 100 unconfirmed replies

array (Reply)
JSON Schema  Expand source
Reply
Type
object
Required content, date_received, message_id, reply_id, source_number, username

Properties

Name
Description
Type
Default
content

Content of message.

string
date_received

Date time when the reply was received in ISO8601 format.

string (date-time)
message_id

Unique identifier of the message that this reply was matched to.

string (uuid)
reply_id

Unique identifier of this reply.

string (uuid)
source_number

Address from which this reply was received from.

string
username

Username that received this reply.

string
JSON Schema  Expand source
Report
Type
object
Required delay, delivery_report_id, date_received, message_id, source_number, status, username

Properties

Name
Description
Type
Default
delay

Not used

integer
0
delivery_report_id

Unique identifier of this delivery report.

string (uuid)
date_received

Date time when the delivery report was received in ISO8601 format.

string (date-time)
message_id

Unique identifier of the message that this delivery report was matched to.

string (uuid)
source_number

Address from which this delivery report was received.

string
status

The status of the message as per the delivery report.

string
username

Username that received this reply.

string
JSON Schema  Expand source
Reports
Type
object
Required delivery_reports

Properties

Name
Description
Type
Default
delivery_reports

The oldest 100 unconfirmed delivery reports.

array (Report)
JSON Schema  Expand source
ReceivedMessage

Description

A message received for the account specified. This message may be in response to a sent message, or it may be an unsolicited message, matched to the account by the destination address.

Type
object

Properties

Name
Description
Type
Default
account

Account associated with this message.

string
action

Action that was invoked for this message if any.

string
content

Content of the message.

string
destination_address

Address this message was delivered to. If this message was received in response to a sent message, this is the source address of the sent message.

string
destination_address_country

Country associated with the destination address.

string (ISO-3066 alpha-2)
format

Format of message.

string
SMS
id

Unique identifier for this message.

string (uuid)
in_response_to

If this message was received in response to a sent message, this is the ID of the sent message.

string (uuid)
metadata

If this message was received in response to a sent message, this is the metadata associated with the sent message.

object
source_address

Address this message was received from. If this message was received in response to a sent message, this is the destination address of the sent message.

string
source_address_country

Country associated with the source address.

string (ISO-3066 alpha-2)
timestamp

Date time at which this message was received.

string (date-time)
JSON Schema  Expand source
ReceivedMessages
Type
object

Properties

Name
Description
Type
Default
page

The current page of results.

integer
page_size

The amount of results returned per page.

integer
total_count

The total number of results in the results set.

integer
page_count

The total number of pages in the results set.

integer
next_uri

Link to the next page of results.

string
previous_uri

Link to the previous page of results.

string
data

List of received messages

array (ReceivedMessage)
JSON Schema  Expand source
SentMessage
Type
object

Properties

Name
Description
Type
Default
account

Account associated with this message.

string
billing_units

Billing units used to send this message.

integer
content

Content of the message.

string
delivered_timestamp

If a delivery report was requested for this message, this is the time at which the message was delivered (or failed to be delivered) to the destination address.

string (date-time)
delivery_report

Indicates if a delivery report was requested for this message.

boolean
destination_address

Address this message was delivered to.

string
destination_address_country

Country associated with the destination address.

string (ISO-3066 alpha-2)
format

Format of message.

string
SMS
id

Unique identifier for this message.

string (uuid)
in_response_to

If this message was sent in response to a received message (an auto response message for example) this is the ID of the received message.

string (uuid)
metadata

Metadata associated with this message.

object
source_address

Address this message was sent from.

string
source_address_country

Country associated with the source address.

string (ISO-3066 alpha-2)
timestamp

Date time at which this message was submitted to the API, refer to the delivered timestamp for the time at which the message was delivered (or failed to be delivered) to the destination address.

string (date-time)
JSON Schema  Expand source
SentMessages
Type
object

Properties

Name
Description
Type
Default
page

The current page of results.

integer
page_size

The amount of results returned per page.

integer
total_count

The total number of results in the results set.

integer
page_count

The total number of pages in the results set.

integer
next_uri

Link to the next page of results.

string
previous_uri

Link to the previous page of results.

string
data

List of sent messages

array (SentMessage)
JSON Schema  Expand source
SubmittedMessage
Type
object

Properties

Name
Description
Type
Default
callback_url

URL replies and delivery reports to this message will be pushed to.

string (url)
content

Content of message.

string
destination_number

Destination number of the message.

string
delivery_report
boolean
format

Format of message.

string
SMS
message_expiry_timestamp

Date time after which the message is considered expired in ISO8601 format.

string (date-time)
metadata

Metadata for the message specified as a set of key value pairs, each key must be no longer than 100 characters, each value must be no longer than 256 characters.

{
   "myKey": "myValue",
   "anotherKey": "anotherValue"
}
object
scheduled

Date time at which the message is scheduled for in ISO8601 format.

string (date-time)
source_address
string
source_address_type

Type of source address specified.

string
message_id

Unique identifier for this message.

string (uuid)
status

Status of the message.

string
JSON Schema  Expand source