Receiving MMS-DLR via HTTP (Webhook)

Introduction

MMS-DLR messages can be delivered from the API to an HTTP endpoint.

Prerequisites

To begin receiving MMS-DLR messages via HTTP, a few items are required:

HTTP Capable Server
JSON Parser
An MMS capable DID (Direct Inward Dial)
A Switch that is MMS enabled and pointing to the HTTP endpoint

Authorization

You may add authorization to your HTTP endpoint.
Available Authorization methods include:

None
Basic
Bearer

Request Sample Format

POST /inbound HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json; charset=utf-8
User-Agent: oxy-http-mailer/1.0
X-Message-ID: 01HMH90R46YBTZVK2FP2QBD7J2
X-Message-Format: oxy-json/1.0

{
  "id": "01HMH90R46YBTZVK2FP2QBD7J2",
  "kind": "mms_delivery_report_req",
  "inserted_at": "2020-05-15T15:00:00.000000Z",
  "timestamp": "2020-05-15T15:00:00.000000Z",
  "from": "12003004000",
  "to": [
    "12003004001"
  ],
  "csp_campaign": {
    "id": "74341b5b-fb66-4570-b318-d4ba587318e9",
    "tcr_brand_id": "B123456",
    "tcr_campaign_id": "C123456"
  },
  "remote_service_provider": "ACME Corp",
  "remote_reference_id": "us_acme",
  "status_code": "Forwarded",
  "data": {
    "headers": {
      "to": "+12003004001/TYPE=PLMN",
      "from": "+12003004000/TYPE=PLMN",
      "cc": "+12003004001/TYPE=PLMN, +12003004002/TYPE=PLMN",
      "x-mms-mm-status-code": "Forwarded"
    },
    "encoding": "plain",
    "body": "",
    "is_multipart": false,
    "parts": []
  },
  "metadata": {
    "to": [
      "+12003004001"
    ],
    "cc": [
      "+12003004001",
      "+12003004002"
    ],
    "recipients": [
      "+12003004001",
      "+12003004002"
    ]
  },
  "mms": {
    "id": "01E7NBVFJA6GQTEEV0YAQP9EMT"
  }
}

Request Parameters

Parameters marked with * are mandatory in all requests.

Parameter	Type	Description	Example
Root
id *	String	The ID used to identify the message.	"01E7NBVFJA6GQTEEV0YAQP9EMT"
timestamp *	Datetime (ISO8601 format)	The timestamp when the message was sent from Tychron's mailing system.	"2020-04-18T11:30:00.000000Z"
inserted_at *	Datetime (ISO8601 format)	The timestamp when the message was received by Tychron's system initially.	"2020-04-18T11:30:00.000000Z"
kind *	String	Denotes whether the message is an MMS Forward Request, or an MMS Delivery Report Request.	"mms_delivery_report_req"
from *	String	The sending number that will appear in the message. The number is typically formatted in a plain format, e.g. (12003004000), however MMS may also be received from the network and can be a Sender ID instead (e.g. "Rogers").	"12003004000"
to *	Array<String>	The recipient numbers. The numbers will be formatted in a plain format, e.g (12003004000). The MMS API currently does not support multiple recipients, but this field is provided as a list.	["12003004001"]
remote_service_provider	String	The carrier or service provider of the remote_number, is typically taken from the original MMS.	"ACME Corp."
remote_reference_id	String	A Tychron issued ID for grouping service providers for billing purposes.	"us_acme"
status_code *	String	An MMS Status code, normalize (downcase or upcase) this value before use, as it is taken from the x-mm-status-code header directly.	"Forwarded"
metadata *	Metadata	A map containing miscellaneous information about the request.
data *	Part	Unlike forward requests, DLRs typically only have 1 part with no body, only headers.
csp_campaign	CSPCampaign	A map containing basic information on the Campaign associated with this message.
mms	MMS	A map containing only the ID of the respective MMS this DLR belongs to.
Metadata
to	Array<String>	A list of numbers found in the `headers.to`.
cc	Array<String>	A list of numbers found in the `headers.cc`.
bcc	Array<String>	A list of numbers found in the `headers.bcc`.
recipients	Array<String>	Combined list of `to`, `cc` and `bcc`.
*	Any	May contain any other key and value pairs.
Part
headers *	Map<String, String>	A map containing header pairs, keys are downcased for easy indexing.
encoding *	String	An encoding that is applied to the message part's body. The encoding can be either base64 or identity.	"base64"
body *	String	A string containing the part's body or data, this will be encoded according to the value of encoding.	"SGVsbG8sIFdvcmxk"
is_multipart *	Boolean	Denotes whether the message contains more than one part, typically MMS messages will always be multipart, but in some rare instances they may just be a large text blob.	false
parts	Array<Part>	If this part has is_multipart set, then this field will be populated with the further sub parts of the message.
CSPCampaign
id	String	The Tychron issued UUID for the campaign.	"c045cf8c-0d97-4241-9f03-1a80ba1d7acb"
tcr_brand_id	String	TCR issued Brand ID.	"B123456"
tcr_campaign_id	String	TCR issued Campaign ID.	"C123456"
MMS
id	String	The Tychron ULID for the original MMS.	"01E7NBVFJA6GQTEEV0YAQP9EMT"

Message parts are recursive and can be divided into multiparts.
If a message part is a multipart, its body is normally empty.

All metadata fields are optional.
to, cc, bcc and recipients fields are provided for convenience, in the case of group messaging, the to or cc fields may be populated.
recipients is a list that contains all aforementioned addresses where possible.
Only the local part of the header's addresses is extracted into the metadata fields.

Response Sample Format

The MMS mailer will accept any 20x status between 200 and 204.
Any 4xx or 5xx status codes will be treated as a temporary failure and will automatically be requeued for delivery.

No Content Response

HTTP/1.1 204 No Content
X-Header: Anything-you-want

OK Response

HTTP/1.1 200 OK
X-Header: Anything-you-want

References

Status Codes

These are the original MM4 status codes provided as is.

Expired
Retrieved
Rejected
Deferred
Indeterminate
Forwarded
Unrecognised

Plain Format

The plain format contains only the digits of the phone number with no additional prefixes. It is almost identical to the E.164 format but without the prefix.

Examples: 12003004000, 332828373552

Encodings

identity: The message body is sent exactly as is.
base64: The message body is encoded using base64.