REST Email API

Overview

Our REST API has been extended to allow the scheduling and sending of basic, plain text Email messages. It is intended as a supplement to the REST API for SMS, as an alternative delivery channel for SMS type (transactional) messages.

While this API is similar to the REST API, it is separate, please note this API has a separate end point for email requests.

Emails will be plain text only, there is no provision for html, rich text or attachments.

HTTPS use is mandatory, all attempts to use plain-text HTTP will be redirected to HTTPS. Request and response data requires JSON encoding. Only HTTP GET and POST methods are required.

Authentication

HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.

Your gateway application credentials (‘application name’ and password) are available in the The Optus SMS Suite platform, under Mobile Gateway API, Rest Email API.

You will need a login email and password to retrieve these. If you do not have these details, please contact optussd@modicagroup.com.

Authorised IP Addresses

Allow-list your servers’ IPs or IP ranges using the ‘Add IP Address’ button under “Authorised IP Addresses”

Note: once one or more IP addresses or IP ranges have been added, SMPP connections from all other IP addresses will be rejected. Any attempt from an IP not in the list will receive an Authentication error.

Base URL

All API access is over HTTPS, and accessed from:

https://api.sms.optus.com.au/rest/email/v1

Versions

The REST API version is currently v1. The media type can just be set to:

Accept: application/json

Error Codes

The following errors can occur:

Sending Email POST request

To send an email message to a single destination, submit a POST request:

POST /message
 
{
  "from": str:name@domain.com,
  "to": str:name@domain.com,
  "subject": str:subject line for email,
  "body": str:message content
}

Optional Attributes

{
  "scheduled": str: 2017-05-05T10:00:00+12:00,
  "reply_to": str:name@domain.com,
  "reference": str:alt-reference,
  "sender": str:name@domain.com, 
}

Scheduled Date Limitation: The upper maximum for scheduled messages is 60 days ahead.

On Success

HTTP/1.1 201 Created
 
Content-Type: application/json
 
int:integer($int64):message-id

Note: All message IDs will be returned as 64bit Signed Integers

On Validation Error

HTTP/1.1 400 Bad Request

{
  "code": int:error-code
  "message": str:error-desc
}

Scheduled Date Validation Error

{
  "error-desc": "Invalid scheduled timestamp (must be less than 60 days)",
  "error": "invalid_attrib"
}

Retrieving a Message

To retrieve a message submit a GET request:

Get message/id/

If a match is found:

HTTP/1.1 200 OK
 
Location: https://api.sms.optus.com.au/rest/email/v1/message/int:message-id
 
{
  "id": int:integer($int64):message-id,
  "from": str:name@domain.com,
  "to": str:name@domain.com,
  "subject": str:subject line for email,
  "body": str:message content
}

Note: All message IDs will be returned as 64bit Signed Integers

Additional Attributes

{ 
  "scheduled": str: RFC3339 date,
  "reply_to": str:name@domain.com,
  "reference": str:alt-reference,
  "sender": str:name@domain.com,
}

If not found:

HTTP/1.1 400 Bad Request

DLR Callback

You will only receive DLR Status messages if you have supplied a DLR Status in The Optus SMS Suite platform REST EMAIL page under Mobile Gateway (API).

NOTE: The security cert must match the domain name being used; self-signed certs will not verify and will generate errors.

The final DLR status for emails only indicate the message was SENT.

No status is available after that point, and read receipts are not supported.

When a DLR message is received for you a POST request is made to the DLR callback URL, this callback will include the DLR Status detail as a JSON object in the body of the POST request.

POST callback-url
 
{
  "message_id": integer($int64):message-id,
  "status": str:dlr-status
}

Note: All message IDs will be returned as 64bit Signed Integers

In the case that the MT message contained a reference, an additional “reference” attribute is added:

{ 
  "reference": str:alt-reference
}

Message Status

The following are the status codes that our message gateway supports for email.

Help

Having trouble integrating with any of our services? Visit our helpdesk at https://sms.optus.com.au/docs/ or contact optussd@modicagroup.com and we’ll help you sort it out.