NAV

MMS

Introduction

Mblox offers Multimedia Messaging Service (MMS) capabilities in the United States. MMS is an extension of Short Messaging Service (SMS) and provides a number of enhanced content options when interacting with clients. The most common uses are for sending pictures and videos. MMS can easily be added for communications by utilizing existing short code channels already established with SMS. This documentation describes the Mblox MMS API that will allow you to add MMS capabilities to your campaigns. Mblox requests that you read this document fully before you get started. Please contact Mblox (support@mblox.com) if you need assistance.

Interfaces

MM7

Introduction

MMS APIs are currently offered via an implementation of the MM7 protocol. MM7 is the standard protocol used by the carriers to send and receive MMS messages. It is a SOAP based protocol sent over HTTP. MM7 supports the following API actions:

Action Functionality
MM7_Submit. Send an MT Message to a device.
MM7_Deliver Receive an MO message from the device.
MM7_Delivery Receive a Delivery report for a previously submitted MT MMS Message.

The use of our MM7 API is only available for accounts with a paid plan. We support submitting MMS messages with MM7 version 5.3.0 to 6.8.0. Your VASPID will be your API Key. We will also issue you a VASID to submit with your message. The VASID will be unique on each short code. All traffic is encrypted in transit via SSL/TLS.

Finding your VASPID (API Key)

You must first request access to the API from your account manager. Once the API is turned on, you can find your API Key in the API Settings page under your ‘Account’ dropdown. Alternatively your account manager will provide you with the Key. You can reset the Key at any time to revoke access. Your username and password for your account are seperate from your API key so you do not have to worry about a account password reset affecting your services.

Finding your VASID

Your account manager will provide you with a VASID for each shortcode. If you use a dedicated shortcode you can pick your own VASID or we can configure it empty.

Receiving Delivery Reports and MO’s

Your Delivery Report URL and MO URL is configured in your Account’s API Settings page. You can update it at any time. SOAP requests will be forwarded to your server every second and require an HTTP STATUS 200 and a proper MM7 SOAP Response or else we will retry. You can also turn off the SOAP notifications to your server and download a CSV of final message statues from the User Interface.

We expect your server to accept our postback within 10 seconds by responding with a standard HTTP STATUS 200 header (success) and proper SOAP Response with matching MM7 TransactionID and Status 1000. If establishing a connection to your Postback URL takes longer than 10 seconds, the connection will time out and be dropped. If the connection times out or the HTTP code is not 200 we will retry the notification again five minutes later for a maximum of 5 retries per notification.

API Limitations

You may have a throughput limit on your account. If your API requests exceed the throughput on your account then you may have some latency in the delivery of your messages. There may also be limits on the number of API calls allowed per second/minute/day. These limits will be published in your API Settings page. If you exceed this limit then your messasge will be rejected and you will be required to retry the request.

Authentication

We authenticate your account with your VASPID and we authenticate your short code, service and carrier reach with the VASID. We can optionally whitelist your IP Address or apply a “basic authorization” username and password requirement to your account which adds an additional level of security to your request.

Special Considerations

Always Use International Number Format: You must use international format when submitting an MM7 message to Mblox. International format includes both the country code with the phone number. We use the country code to determine routing of the message. There should be no dialing prefixes (eg 00 or 001) or special characters such as the plus symbol when submitting messages. (example: '642111111’ not ’+642111111’). If you submit a message without a country code the message will likely get routed to the wrong country and you may end up paying for the delivery there.

For example the US number (774)-319-9144 in international number format would be 17743199144 because the USA country code is 1.

MM7_Submit

Send MMS MT to end users

To send a multimedia message, you send an MT message as a submit request to Mblox and supply the multimedia message as the payload. When Mblox accepts your MT message, we respond to you with a success status using “SubmitRsp” response. This indicates that your message was accepted for delivery. It does not, however, indicate that your message was delivered to the device. If the MT message was received in error, we respond to you with a failure status using SOAP fault “RSErrorRsp” response.

Using the mobile operator ID in an MM7 request

You can supply the mobile operator details as an ID in the request header of an MM7 “SubmitReq” request. If you do not supply the mobile operator, Mblox would look it up (this may be a separately charged fee, depending on your contract). The same mobile operator ID is returned in the HTTP header of delivery reports and MO requests. For the best throughput performance, you should include the mobile operator ID in each request, otherwise an operator lookup is needed before we can forward the message to the mobile operator.

SMIL is Required

SMIL is required in all the SubmitReq MM7 Requests. Its an XML based language to write interactive multimedia presentations. More information about SMIL can be found here: http:www.w3.org/TR/SMIL/.

Header Name Description Mandatory
X-Mblox-Operator-Id Mblox Mobile Operator ID.
Examples: Verizon=31003.
See all Mblox Operator IDs.
No

MM7_Submit.REQ

Supported MM7 SOAP envelope request elements

Element Description Mandatory
TransactionID The identification of the MM7 SubmitReq/SubmitRsp pair. It is located in the SOAP header. You supply this in the MM7 SubmitReq and Mblox returns it in the corresponding SubmitRsp. Yes
SubmitReq Identifies the message as an MMS MT submit. This is the message type for an MT request. Yes
MM7Version Identifies the MM7 Version.
(Supported versions are ver-5.3.0 and ver-6.8.0)
Yes
VASPID Mblox provides an API key after your account is provisioned which is your VASPID. Yes
VASID Your account manager will provide you with a VASID for each shortcode. It is mandatory for accounts using shared shortcodes, otherwise optional. No
SenderAddress This is your shortcode. Should be provisioned and configured to your account and service. Yes
Recipients The mobile phone number of the end user. This must be a valid mobile number in international format without a leading + symbol; for example: 12515550123 (US) and 447700900750 (UK). Multiple numbers are NOT supported. Yes
Subject Title of the whole multimedia message. Recommended size is 80 characters. No
Content Content of the multimedia message. href:cid attribute links to attachment. Yes
allowAdaptations Indicates if you wish to allow the mobile operator to re-encode (transcode) the content to make the content more suitable to the target handset. Each mobile operator may choose to obey or ignore this field; for example, some mobile operators assume or require by default the option to transcode content. AllowAdaptations is an attribute of Content element. The value must be Boolean (either true or false). The default is true. No

See Unsupported elements for MM7_Submit.

Example

<?xml version="1.0" encoding="UTF-8"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Header>
        <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" soap-env:mustUnderstand="1">1000001</TransactionID>
    </soap-env:Header>
    <soap-env:Body>
        <SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
            <MM7Version>6.8.0</MM7Version>
            <SenderIdentification>
                <VASPID>skfdjslkjfdslkfj434das</VASPID>
                <VASID>126273</VASID>
                <SenderAddress>
                    <ShortCode>111122</ShortCode>
                </SenderAddress>
            </SenderIdentification>
            <Recipients>
                <To>
                    <Number>16172383232</Number>
                </To>
            </Recipients>
            <Subject>My first MM7 Message</Subject>
            <Content allowAdaptations="false" href="cid:generic" />
        </SubmitReq>
    </soap-env:Body>
</soap-env:Envelope>

MM7_Submit.RES

Supported MM7 SOAP envelope response elements

Element Description
TransactionID The identification of the MM7 SubmitReq/SubmitRsp pair. It is located in the SOAP header. You supply this in the MM7 SubmitReq and Mblox returns it in the corresponding SubmitRsp.
SubmitRsp Identifies the message as a MM7 Submit Response. This is the message type for an MT response.
MM7Version Identifies the MM7 Version.
(Supported versions are ver-5.3.0 and ver-6.8.0)
StatusCode MT message submit acception/rejection is based on Success/Failure status code. “Success” response does not mean the message was delivered to the handset.
See all Status Codes
StatusText Description of the status code.
MessageId If the MT message submit is successful then this contains the Mblox generated ID of the submitted message. This ID is expected in the delivery reports relating to this message.

Example: Success

Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
   <soap-env:Header>
      <TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
   </soap-env:Header>
   <soap-env:Body>
      <SubmitRsp>
         <MM7Version>6.8.0</MM7Version>
         <Status>
            <StatusCode>1000</StatusCode>
            <StatusText>Successfully parsed and validated request</StatusText>
         </Status>
         <MessageID>369500617770864640</MessageID>
      </SubmitRsp>
   </soap-env:Body>
</soap-env:Envelope>

Example: Failure

Failure
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
   <soap-env:Header>
      <TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
   </soap-env:Header>
   <soap-env:Body>
       <soap-env:Fault>
            <faultcode>soap-env:Client</faultcode>
            <faultstring>Client error</faultstring>
            <detail>
                  <RSErrorRsp>
                    <MM7Version>6.8.0</MM7Version>
                    <Status>
                        <StatusCode>2007</StatusCode>
                        <StatusText>Unable to parse request</StatusText>
                        <Details>Message format corrupt</Details>
                    </Status>
                  </RSErrorRsp>
            </detail>
        <soap-env:Fault>
   </soap-env:Body>
</soap-env:Envelope>

MT Submit Full Example

Request:

Request
POST /mm7/v1 HTTP/1.1
Authorization: Basic dW5pdmyc2FsLXZhcj2YWwtdmFzcC1wd2Q=
Host: api.Mblox.com
Accept: */*
Content-Type: multipart/related; boundary="mainBoundary"; type="text/xml"; start="<mm7-start>"
SOAPAction: "http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4"
Content-Length: 45454
X-Mblox-Operator-Id: 31003
Expect: 100-continue

--mainBoundary
Content-Type: text/xml; charset=utf-8
Content-ID: <mm7-start>

```xml
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" SOAP-ENV:mustUnderstand="1">555e29f8879be</TransactionID>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <SubmitReq>
            <MM7Version>6.8.0</MM7Version>
            <DeliveryReport>true</DeliveryReport>
            <SenderIdentification>
                <VASPID>spUsdstW2u6GbvnMOsdseXrBa7NNLwTdKL</VASPID>
                <VASID>61295</VASID>
                <SenderAddress>
                    <ShortCode>111122</ShortCode>
                </SenderAddress>
            </SenderIdentification>
            <Recipients>
                <To>
                    <Number>16179593069</Number>
                </To>
            </Recipients>
            <Subject>My first MM7 Message</Subject>
            <ExpiryDate>2015-05-24T18:54:48+00:00</ExpiryDate>
            <TimeStamp>2015-05-21T18:54:48+00:00</TimeStamp>
            <Content allowAdaptations="false" href="cid:generic_content_id"/>
        </SubmitReq>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

--mainBoundary
Content-Type: multipart/related; start="<mms.smil>";
         boundary="subBoundary"; type="text/xml"
Content-ID: <generic_content_id>

--subBoundary
Content-Type: text/plain; charset=utf-8
Content-ID: <132c4ca56a209475>

MM7 Test Text
--subBoundary
Content-Type: application/smil; charset=utf-8
Content-ID: <mms.smil>

<?xml version="1.0" encoding="UTF-8"?><smil><head><layout><root-layout width="100%" height="100%"/><region id="Text" top="50%" left="0" height="50%" width="100%" fit="hidden"/></layout></head><body><par><text src="cid:132c4ca56a209475" region="Text"/></par></body></smil>
--subBoundary--

--mainBoundary--

Response:

Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Mon, 16 Mar 2015 17:46:59 GMT
Server: Apache
Vary: Accept-Encoding,User-Agent
Content-Length: 715
Connection: keep-alive


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
   <soap-env:Header>
      <TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
   </soap-env:Header>
   <soap-env:Body>
      <SubmitRsp>
         <MM7Version>6.8.0</MM7Version>
         <Status>
            <StatusCode>1000</StatusCode>
            <StatusText>Successfully parsed and validated request</StatusText>
         </Status>
         <MessageID>369500617770864640</MessageID>
      </SubmitRsp>
   </soap-env:Body>
</soap-env:Envelope>

MM7_Deliver

Receive MMS MO submitted by end users to your platform

Mblox delivers messages from end users to your platform by supplying the MMS as the payload of the request message. The deliver request is made using MM7 SOAP “DeliverReq”. Message include identification of the request that is used by your platform to correlate a response to the message. Your platform must reply with a SOAP response “DeliverRsp”, indicating that the message was successfully received and will be processed. If you cannot identify the requested content or if the delivered content does not fulfill the conditions you’d expect, then your platform should indicate a failure in the “DeliverRsp” status field.

MM7_Deliver.REQ

MM7 MO deliver request elements

1. HTTP header elements

Header Name Description Mandatory
X-Mblox-Operator-Id Mblox Mobile Operator ID.
Examples: Verizon=31003.
See all Mblox Operator IDs.
No

2. Elements in the SOAP header and body

Element Description Returned
TransactionID It is a Mblox generated transaction ID.Identifies the DeliverReq/DeliverRsp pair. Always
DeliverReq Identifies the message as an MM7 deliver request. Always
MM7Version Identifies the MM7 Version.
(Supported versions are ver-5.3.0 and ver-6.8.0)
Always
Sender The mobile phone number of the end user. This must be a valid mobile number in international format without a leading + symbol; for example: 12515550123 (US) and 447700900750 (UK). Always
Recipients The address of the message recipients i.e., Shortcode/Longcode Always
LinkedID Identifier for the MO message. This is a Mblox generated ID. Always
TimeStamp The date and time of the submission of the MO message. This value is in UTC. Always
Priority The priority (importance) of the message. Possible values: High, Normal, Low Only when provided by mobile operator
Subject Title of the whole multimedia message. Only when provided by mobile operator
Content A reference to the content of the MM7 message. Contains an “href:cid” attribute that links to the content ID of the first attachment in the MM7 message. Only when provided by mobile operator
UACapabilities Information about the capabilities of the MMS user agent that originated the multimedia message. In this context, the associated timestamp is not populated. Only when provided by mobile operator

See Unsupported elements

Example

Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env::Header>
   <TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env::Header>
<soap-env::Body>
   <DeliverReq>
      <MM7Version>6.8.0</MM7Version>
      <LinkedID>1000001</LinkedID>
      <Sender>
         <Number>1617423433</Number>
      </Sender>
      <Recipients>
         <To>
         <Number displayOnly="false">111122</Number>
         </To>
      </Recipients>
      <TimeStamp>2014-04-14T16:15:23.414Z</TimeStamp>
      <Priority>Normal</Priority>
      <Content href="cid:default.cid" allowAdaptations="true"/>
   </DeliverReq>
</soap-env:Body>
</soap-env:Envelope>

MM7_Deliver.RES

MM7 MO deliver response elements

Your system should respond to the deliver request with a deliver response containing the elements described in the following table.

Element Description
TransactionID Identifies the DeliverReq/DeliverRsp pair. It is part of the SOAP header. The value returned is the one provided in the request.
DeliverRsp Identifies the message as a MM7 Deliver Response.
MM7Version Identifies the MM7 Version.
(Supported versions are ver-5.3.0 and ver-6.8.0)
StatusCode A code that indicates whether you recieved the MO message request successfully. The status code for successful deliver is 1000.
See all Status Codes
StatusText Description of the status code.

Example

Response
<?xml version="1.0" encoding="UTF-8" ?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap-env:Header>
   <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
   <DeliverRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
      <MM7Version>6.8.0</MM7Version>
      <Status>
         <StatusCode>1000</StatusCode>
         <StatusText>Successfully received MMS</StatusText>
      </Status>
   </DeliverRsp>
</soap-env:Body>
</soap-env:Envelope>

Receive MMS MO Full Example

Request

Request
POST / HTTP/1.1
SOAPAction: "http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4"
Content-Type: multipart/related; start="soap-start"; type="text/xml";
        boundary="----=_Part_139078_1411587550.1397492135426"
Host: api.Mblox.com
Content-Length: 2546
X-Mblox-Operator-Id: 31003
Connection: Keep-Alive

------=_Part_139078_1411587550.1397492135426
Content-Type: text/xml
Content-ID: <soap-start>


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env::Header>
   <TransactionID soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env::Header>
<soap-env::Body>
   <DeliverReq>
      <MM7Version>6.8.0</MM7Version>
      <LinkedID>1000001</LinkedID>
      <Sender>
         <Number>1617423433</Number>
      </Sender>
      <Recipients>
         <To>
         <Number displayOnly="false">111122</Number>
         </To>
      </Recipients>
      <TimeStamp>2014-04-14T16:15:23.414Z</TimeStamp>
      <Priority>Normal</Priority>
      <Content href="cid:default.cid" allowAdaptations="true"/>
   </DeliverReq>
</soap-env:Body>
</soap-env:Envelope>

------=_Part_139078_1411587550.1397492135426
Content-Type: multipart/mixed;
        boundary="----=_Part_139079_1300104441.1397492135426"
Content-ID: <default.cid>

------=_Part_139079_1300104441.1397492135426
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: image_0.jpg
<Binary contents>

------=_Part_139079_1300104441.1397492135426
Content-Type: text/plain
Content-Transfer-Encoding: binary
Content-ID: text_0.txt
Test MO message!

------=_Part_139079_1300104441.1397492135426--

------=_Part_139078_1411587550.1397492135426--

Response

Response
HTTP/1.1 200 OK
Server: Apache
Content-Type: application/xml; charset=utf-8
Content-Length: 715
Date: Mon, 16 Mar 2015 17:46:59 GMT


<?xml version="1.0" encoding="UTF-8" ?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap-env:Header>
   <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
   <DeliverRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
      <MM7Version>6.8.0</MM7Version>
      <Status>
         <StatusCode>1000</StatusCode>
         <StatusText>Successfully received MMS</StatusText>
      </Status>
   </DeliverRsp>
</soap-env:Body>
</soap-env:Envelope>

MM7_DeliveryReport

Receive Delivery Reports for previously submitted MT

Mblox sends delivery reports using the MM7 Delivery Report message type i.e., “DeliveryReportReq”. The delivery report indicates the current state of the original submit request message. We will send a delivery report to your platform only when the appropriate information is available. If the delivery report message is accepted or rejected then respond with an “DeliveryReportRsp”, including a status that indicates why the delivery report was accepted/rejected. For information about the status codes returned for Delivery Reports, please See Delivery report status.

MM7_DeliveryReport.REQ

MM7 delivery report request elements

Element Description Returned
TransactionID This identifies the DeliveryReportReq/DeliveryReportRsp pair. It is Mblox generated ID. Always
DeliveryReportReq Identifies the message as an MM7 Delivery Report. Always
MM7Version Identifies the MM7 Version.<br/(Supported versions are ver-5.3.0 and ver-6.8.0)
Recipient The mobile phone number of the end user. This must be a valid mobile number in international format without a leading + symbol; for example: 12515550123 (US) and 447700900750 (UK). Always
Sender Your shortcode. This should match the same information that is linked in the MT configuration, and generally to the service you are providing. Always
MessageID Mblox generated ID linked to the submitted message. This ID was returned to your system in the initial response (SubmitRsp) to your MT MMS request. Always
Date The date and time of the submission of the multimedia message (timestamp). Value is in UTC. Always
MMStatus A code that indicates whether the MT message was delivered successful or failed. For information about the status codes returned for Delivery Reports, please See Delivery report status. Always
UACapabilities Also known as MMS User Agent capabilities. This describes the capabilities of the MMS User agent of the mobile handset. Only when provided by mobile operator

See Unsupported elements.

Example

Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env:Header>
   <TransactionID soap-env:mustUnderstand="1">10000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
   <DeliveryReportReq>
      <MM7Version>6.8.0</MM7Version>
      <MessageID>369500617770864640</MessageID>
      <Recipient>
         <Number>16175550123</Number>
      </Recipient>
      <Sender>
         <Number>111122</Number>
      </Sender>
      <Date>2015-03-16T14:03:51.749Z</Date>
      <MMStatus>Retrieved</MMStatus>
      <StatusText>Success</StatusText>
      <UACapabilities UAProf="Samsung Galaxy" />
   </DeliveryReportReq>
</soap-env:Body>
</soap-env:Envelope>

MM7_DeliveryReport.RES

MM7 delivery report response elements

Your system should respond to the delivery report request with a delivery report response containing the elements described in the following table.

Element Description
TransactionID Identifies the DeliveryReportReq/DeliveryReportRsp pair. It is part of the SOAP header. The value that was provided with the deliveryReportReq is returned.
DeliveryReportRsp Identifies the message as an MM7 Delivery Report Response.
MM7Version Identifies the MM7 Version.
(Supported versions are ver-5.3.0 and ver-6.8.0)
StatusCode A code that indicates whether you recieved the MO message request successfully. The status code for successful deliver is 1000.
See all Status Codes
StatusText Description of the status code.

Example

Response
<?xml version="1.0" encoding="UTF-8" ?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap-env:Header>
   <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
   <DeliveryReportRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
      <MM7Version>6.8.0</MM7Version>
      <Status>
         <StatusCode>1000</StatusCode>
         <StatusText>Successfully Received MMS.</StatusText>
      </Status>
   </DeliveryReportRsp>
</soap-env:Body>
</soap-env:Envelope>

Delivery Report Full Example

Request

Request
POST / HTTP/1.1
SOAPAction: "http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4"
Content-Type: multipart/related; type="text/xml";
Host: api.Mblox.com
Content-Length: 2546
X-Mblox-Operator-Id: 31003
Connection: Keep-Alive


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns=
"http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
<soap-env:Header>
   <TransactionID soap-env:mustUnderstand="1">10000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
   <DeliveryReportReq>
      <MM7Version>6.8.0</MM7Version>
      <MessageID>369500617770864640</MessageID>
      <Recipient>
         <Number>16175550123</Number>
      </Recipient>
      <Sender>
         <Number>111122</Number>
      </Sender>
      <Date>2015-03-16T14:03:51.749Z</Date>
      <MMStatus>Retrieved</MMStatus>
      <StatusText>Success</StatusText>
      <UACapabilities UAProf="Samsung Galaxy" />
   </DeliveryReportReq>
</soap-env:Body>
</soap-env:Envelope>

Response

Response
HTTP/1.1 200 OK
Server: Apache
Content-Type: text/xml; charset=utf-8
Content-Length: 539
Date: Mon, 16 Mar 2015 14:03:32 GMT

<?xml version="1.0" encoding="UTF-8" ?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap-env:Header>
   <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4" soap-env:mustUnderstand="1">1000001</TransactionID>
</soap-env:Header>
<soap-env:Body>
   <DeliveryReportRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
      <MM7Version>6.8.0</MM7Version>
      <Status>
         <StatusCode>1000</StatusCode>
         <StatusText>Successfully Received MMS.</StatusText>
      </Status>
   </DeliveryReportRsp>
</soap-env:Body>
</soap-env:Envelope>

Mblox Operator IDs

Operator X-Mblox-Operator-Id
AT&T Wireless US 31002
MetroPCS US 31062
Verizon Wireless US 31003
T-Mobile US 31004
Sprint US 31005

Unsupported MM7 SOAP Elements

MM7_Submit.REQ

Element Behavior Description
ApplicID Stripped This information element contains the identification of the destination application. Upon reception, the recipient MMS VAS Application shall provide this MM7_retrieve.REQ to the specified destination application
AuxApplicInfo Stripped If present, this information element indicates additional application/implementation specific control information
ChargedParty Error An indication which party is expected to be charged for an MM submitted by the VASP, e.g. the sending, receiving, both parties third party or neither. Possible values are “Sender”, “Recipient”, “Both”, “Neither”
ChargedPartyID Error The address/id of the third party which is expected to pay for the MM
ContentClass Stripped Classifies the content of the MM to the smallest content class to which the MM belongs. Possible values are “text”, “image-basic”, “image-rich”, “video-basic”, “video-rich”, “megapixel”, “content-basic”, “content-rich”
DeliveryCondition Stripped If the condition is met the MM shall be delivered to the recipient MMS User Agent, otherwise the MM shall be discarded. The initial values are: MMS capable only; HPLMN only; any other values can be added based on bilateral agreements between the MMS Relay/Server operator and the VASP.
DeliveryReport Default to true A request for delivery report. Boolean value true/false. Ask your account manager to turn off delivery reports.
DistributionIndicator Stripped If set to ‘false’ the VASP has indicated that content of the MM is not intended for redistribution. If set to 'true’ the VASP has indicated that content of the MM can be redistributed. Boolean value true/false
DRMContent Stripped Indicates if the MM contains DRM-protected content. Boolean value true/false
EarliestDeliveryTime Stripped The earliest desired time of delivery of the MM to the recipient (time stamp). Date format is absolute or relative
ExpiryDate Default to 3 days The desired time of expiry for the MM (time stamp). Date format is absolute.
LinkedID Stripped This identifies a correspondence to a previous valid message delivered to the VASP.
MessageClass Pass Through Class of the MM (e.g. “Informational”, “Advertisement”, “Auto”)
Priority Pass Through The priority (importance) of the message. Possible values are “High”, “Normal”, “Low”
ReadReply Stripped A request for confirmation via a read report to be delivered. Boolean true/false value. Set it 'true’ to receive MM7 Read Replies.
ReplyApplicID Stripped If present, this information element indicates a “reply path”. It contains the application identifier which shall be used by the recipient MMS VAS Application when a reply-MM or a read-reply report is created
ReplyCharging Error A request for reply-charging. No value. Presence implies true
replyChargingSize Error In case of reply-charging the maximum size for reply-MM(s) granted to the recipient(s). Optional attribute of ReplyCharging element. Positive integer value
replyDeadline Error In case of reply-charging the latest time of submission of replies granted to the recipient(s) (time stamp). Optional attribute of ReplyCharging element. Date format is absolute or relative
ServiceCode Pass Through Information supplied by the VASP which may be included in charging/billing information. The syntax and semantics of the content of this information are out of the scope of this specification.
TimeStamp Default to Submit time The time and date of the submission of the MM (time stamp)

Unsupported MM7 SOAP Elements

MM7_Deliver.REQ

Element Description
ApplicID The presence of this information element indicates that this abstract message shall be provided to an application residing on an MMS User Agent. It contains the identification of the destination application
AuxApplicInfo If present, this information element indicates additional application/implementation specific control information
MMSRelayServerID Identifier of the MMS Relay/Server
RecipientSPI The SPI of the intended MM recipient, in case the MM was delivered to VASP based on the recipient address
ReplyApplicID If present, this information element indicates a “reply path”, i.e. the identifier of the application to which delivery reports, read-reply reports and reply-MMs are addressed if any
ReplyChargingID In case of reply-charging when the reply-MM is submitted within the MM7_deliver.REQ this is the identification of the original MM that is replied to.
SenderSPI The SPI of the MM originator

MMS Status Codes

StatusCode StatusText Details
1000 Success Successfully parsed and validated request.
2000 Client error Invalid IP Address or Protocol
2002 Address Error Invalid Address
2004 Multimedia refused Carrier refuses content
2007 Unable to parse request Message format corrupt
2550 Account disabled Your account is no longer provisioned for MMS
2551 Account not Provisioned for MM7 Your account is not provisioned for MM7 API
2560 Content length exceeded maximum supported request size Reduce the size of the content you are sending.
2561 Invalid sender identification Sender identification invalid or missing.
2562 Invalid VASID The VASID is your ServiceID
2563 Invalid source address The Shortcode may be incorrect or not provisioned
2564 Invalid VASPID The VASPID is your API Key
2565 Message rejected, reply charging not supported Message rejected, reply charging not supported
2566 Invalid carrier Invalid carrier ID.
2567 Missing carrier ID Carrier ID is required to be passed
2568 Unable to authenticate Ensure the HTTP username and password you have specified are correct and formatted properly within the Authorization header.
2569 Carrier Lookup Service is down, please retry
2500 Missing or Invalid HTTP header Content-Length or Content-Type Ensure the HTTP Content-Length and Content Type header are included and valid.
2502 Missing destination address Ensure the recipient is specified correctly for the MM7 version that is used.
2503 Multiple destination addresses not supported Multiple recipients not supported. Instead, create multiple messages
2504 Missing source address Ensure source address is specified correctly for the MM7 version that is used
2505 Missing or unsupported MM7 Version Ensure specified MM7 version is on the list of supported versions, and is in the format x.y.z
2506 Missing XML element - Content Ensure the Content element is included in the SubmitRequest.
2507 Unsupported namespace Ensure that all the namespaces specified are on the list of supported namespaces.
2510 Missing or Invalid SOAP header Ensure the SOAP envelope contains a SOAP header with only the TransactionID element
2511 Missing or Invalid SOAP body Ensure the SOAP envelope contains a SOAP body with the SubmitReq
2512 Unsupported operation SubmitReq is the only supported operation
2513 Unable to parse attachment Ensure your attachment is specified, and encoded properly
2514 Invalid SOAP attachment header Content-Type Ensure the Content-Type headers of all the attachments are formatted properly
2515 Invalid SOAP body part Content-Type Ensure the Content-Type header of the SOAP body part, aka the SOAP envelope part, is formatted properly
3000 System error Internal system/service error.
3001 Number blacklisted Phone number is blacklisted for receiving messages do not retry
3002 Charged party not supported Charged Party not supported
3003 Multimedia download failed Using URLs in the MM7 the fetch of content failed or took too long
3510 Throughput exceeded Throughput exceeded please retry later
3520 Provisioning issue Provisioning problem, please contact your account manager
3500 Timeout Carrier gateway timeout
4000 General service error Carrier rejects the message due to a general service error
4002 Unsuported MM7 version The carrier does not support this MM7 version
4003 Unsupported operation Carrier rejects the message due to unsupported operation or format
4004 Validation error Validation error
4006 Service unavailable Carrier capacity reached. Retry later
4007 Service denied Carrier denies service for the recipient address

Delivery Report Statuses

The following table lists the responses returned with delivery reports.

Status Status text Description
Deferred Deferred The end user’s handset has retrieved the MMS header, but has not downloaded the full message from the mobile operator. The end user may still download the message at a later time.
Expired Expired The mobile operator could not contact the handset before reaching the expiry time. Each mobile operator has their own expiry times after which they will stop trying to send messages such as an MMS.
Forwarded Forwarded The end user forwarded the MMS to another address without retrieving it.
Indeterminate Indeterminate The mobile operator could not determine if the message was delivered correctly. This occurs when the handset cannot return an MMS delivery report.
NotSupported NotSupported Request is not supported
Rejected Rejected Technical issues/System or Server errors/Content blocked by Mobile Operator/Exceeded MMS Size/ Other errors
Retrieved Success The message was successfully sent to the handset.
Unreachable Unreachable Server/Endpoint is Unreachable
Unrecognized Unrecognized The end user’s handset cannot download the MMS.

Unsupported MM7 SOAP Elements

MM7_DeliveryReport.REQ

Element Description
ApplicID This information element indicates the identification of the application that the delivery report is intended for. If a Reply-Applic-ID was indicated in the corresponding original MM, the recipient MMS Relay/Server shall set its value to that Reply-Applic-ID value. Otherwise, the recipient MMS Relay/Server shall set its value to the Applic-ID value that was indicated in the corresponding original MM
AuxApplicInfo If present, this information element indicates additional application/implementation specific control information. The recipient MMS Relay/Server shall insert it if Aux-Applic-Info was indicated in the corresponding original MM, in which case its value shall equal that Aux-Applic-Info value
MMSRelayServerID Identifier of the MMS Relay/Server
ReplyApplicID If present, this information element indicates a “reply path” to this delivery report, i.e. the identification of an application to which reply-MMs are addressed. The recipient MMS Relay/Server shall insert it into the MM1_DeliveryReport.REQ if the values of Applic-ID and Reply-Applic-ID in the corresponding original MM differ, in which case its value shall equal the Applic-ID value that was indicated in the corresponding original MM

XML

Introduction

Mblox offers MMS capabilities for its customers over the XML API. XML API is known to be the industry standard for sending and receiving rich multimedia content by providing higher throughput and customer satisfaction.

Some of the key features of XML API are:

Mblox XML MMS API Methods:

Action Functionality
saveMMS This API stores an MMS from XML.
sendSavedMMS This API sends stored content from a specified account using an mms-id to a single mobile number.
sendMMS Sends an MMS defined in the XML containing slides of embedded with video, audio, images and/or text to a single or list of mobile numbers in international number format.

saveMMS

Overview
This API stores an MMS from XML. The MMS may contain slides embedded with text, and video, audio, images, PDF, iCal, vCard, Passbook files. Once the MMS is saved, it can be utilized by other functions through the mms-id returned. Note, while elements may be given in any order, the slides are created in the order given in the API call.

Example: saveMMS Request
<request>
    <action>saveMMS</action>
    <api-key>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</api-key>
    <message-subject>The subject</message-subject>
    <name>FuelTheFire</name>
    <slide>
        <image><url>http://www.yoursite.com/images/1.jpg</url></image>
        <audio><url>http://www.yoursite.com/audio/1.mp3</url></audio>
        <message-text>Here is some text</message-text>
        <duration>5</duration>
    </slide>
    <slide>
        <message-text>My Contact</message-text>
        <vcard><url>http://www.yoursite.com/2.vcf</url></vcard>
        <duration>10</duration>
    </slide>
</request>


Request Parameters: Mandatory: action, api_key, subject, name, slide

Optional: image, audio, video, url, text, duration, vcard, ical, pdf, passbook

Response Parameters: status, mmsId, errorCode, errorInfo

Related Error Codes: E223, E224, E225, E226, E227, E228, E229, E230, E301, E302, E303, E304, E331, E332, E333, E334, E335, E336, E337, E338, E341, E351, E352, E353, E355, E356, E357, E358

Response Example: Success

Example: saveMMS Success Response
<response>
    <status>Success</status>
    <mms-id>35674</mms-id>
</response>

Response Example: Failure

Example: saveMMS Failure Response
<response>
    <status>Failure</status>
    <error-code>E111</error-code>
    <error-info>Invalid shortcode</error-info>
</response>

Postback Notifications
When an MMS is saved, the system will generate a Postback notification and unlock MMS for further use. If an MMS contain audio/video, Postback will be sent when the encoding of the MMS audio/video is finished, otherwise Postback notification will be sent instantly. Below is an example of Postback notification when an MMS is saved successfully:

saveMMS Postback notification
<POSTBACK>
    <ORIGIN>MMS_MT</ORIGIN>
    <CODE>N003</CODE>
    <MMSID>35674</MMSID>
</POSTBACK>

If there was an error encoding the MMS audio/video, the system will generate a notification:

saveMMS error Postback Notification
<POSTBACK>
    <ORIGIN>MMS_MT</ORIGIN>
    <CODE>E002</CODE>
    <MMSID>35674</MMSID>
    <AUDIONAME>http://www.yoursite.com/audio/1.mp3</AUDIONAME>
</POSTBACK>

Special Considerations for saveMMS:

sendSavedMMS

Overview
This API sends stored content from a specified account using an MMSID to a single mobile number. FROM must be one of the shortcodes allowed for your account. In case the number is from a different country than the FROM shortcode is assigned to, the default shortcode for those countries will be used.

Content Transcoding:
Every binary MMS we deliver can be transcoded for the destination handset and every web page we deliver is transcoded for the browsing handset. To transcode a binary MMS we must know what type of handset the user has. We are able to obtain this handset type information from delivery receipts and store the record in a handset cache for later use. We have a database of attributes which we manually match to every new handset in the cache so we can adapt the content during MMS delivery.

Our API allows you to dynamically change the text of each slide by setting up optional CUSTOMTEXT (CUSTOMTEXT must include mandatory fields: value and slide) and MMS Subject by setting CUSTOMSUBJECT.

Device Discovery Message (DDM): Device Discovery Message is a short textual MMS message that is sent to the number to discover what handset the end user is using. We store this handset information in our system and reuse it, so a DDM is sent only to new numbers. If the DDM settings are not included within your API call and the number is not in the handset cache we will deliver the MMS with generic settings. If the handset is in the handset cache the DDM will not be sent and the MMS message will be transcoded and delivered immediately. You can force sending of DDM (regardless if number is cached) by setting DDMFORCE to ‘true’

Our API allows you to customize DDM by setting 3 parameters:

Request Parameters:

Mandatory: action, api-key, fallback-sms-text, from, mms-id, service-id, to Optional: custom-subject, custom-text, data, ddm-force, ddm-message-text, ddm-message-subject, ddm-message-timeout, operator-id

Response Parameters: status, to, from, mmsId, trackingId, errorCode, errorInfo

Related Error Codes: E107, E110, E111, E114, E241, E503, E618, E619, E620, E622, E626, E627, E628, E629, E650

Request Example:

Example: sendSavedMMS Request
<request>
    <action>sendSavedMMS</action>
    <api-key>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</api-key>
    <to>14044790000</to>
    <from>28444</from>
    <service-id>12345</service-id>
    <mms-id>35674</mms-id>
    <ddm-message-subject>We are detecting your handset</ddm-message-subject>
    <ddm-message-text>This message is free of charge and will allow us to deliver your content nice and smooth</ddm-message-text>
    <ddm-message-timeout>10</ddm-message-timeout>
    <custom-text>
        <value>My custom text in first slide</value>
        <slide>1</slide>
    </custom-text>
    <custom-subject>My custom subject</custom-subject>
    <data>
        <firstname>Bill</firstname>
        <lastname>Smith</firstname>
        <accountnumber>XYZ23456</accountnumber>
        <pin>13579</pin>
    </data>
</request>

Response Example: Success

Example: sendSavedMMS Success Response
<response>
    <status>Success</status>
    <mms-id>35674</mms-id>
    <tracking-id>TU1TXzU5Nzg3OQ==</tracking-id>
    <to>14044790000</to>
    <from>28444</from>
    <status-details>MMS request accepted and queued for delivery</status-details>
</response>

Response Example: Failure

Example: sendSavedMMS Failure Response
<response>
    <status>Failure</status>
    <error-code>E713</error-code>
    <to>14044790000</to>
    <error-info>There is billing problem on your account</error-info>
</response>

Postback Notifications For SendSavedMMS
When the MMS delivery is processed successfully the system will generate a Postback notification.

sendMMS

Overview
Sends an MMS defined in the XML containing slides of embedded with video, audio, images and/or text to a single or list of mobile numbers in international number format. The sendMMS is a minor extension of the saveMMS function. Note, while elements may be given in any order, the slides are created in the order given in the API call.

While the sendMMS API method allows sending slides containing video elements, it is not recommended as it introduces latency during the call. Therefore, Mblox suggests strongly that you use the saveMMS API call to submit video content and then Mblox MMS service can transcode the contents in advance before you request the sendSavedMMS API call.

If the sendMMS API is used to send the same content to multiple users, at present the Mblox application does not cache this content as such the content will need to be uploaded for each request. This is another reason Mblox suggests that you use combination of saveMMS and sendSavedMMS API calls.

In case of Optimized MMS, there is a mandatory ‘fallback-sms-text’ which is used as the SMS text in the case of MMS is delivered via SMS link. In case of Standard MMS, the ‘fallback-sms-text’ is not required.

MMS “Link Expiration Date’ is used to expire the MMS Link (In the case when MMS fallback to SMS Link). Depending on this expiration date, the content is disabled on this link. By default it expires 365 days from the date the original MMS was created.

Request Parameters: Mandatory: action, api_key, to, from, name, slide, fallback-sms-text, service-id

Optional: operatorid, campaignRef, subject, image, audio, video, url, text, duration, vcard, ical, pdf, passbook, message-text

Response Parameters: status, to, mmsId, trackingId, errorCode, errorInfo

Related Error Codes: All saveMMS Error Codes plus E110, E111, E201, E628

Request Example:

Example: sendMMS Request
<request>
    <action>sendMMS</action>
    <api-key>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</api-key>
    <to>12399471613</to>
    <from>28444</from>
    <operator-id>31062</operator-id>
    <message-subject>The subject</message-subject>
    <service-id>32113</service-id>
    <name>FuelTheFire</name>
    <slide>
        <duration>5</duration>
        <image>
            <url>http://www.yoursite.com/images/1.jpg</url>
        </image>
        <audio>
            <url>http://www.yoursite.com/audio/1.mp3</url>
        </audio>
        <message-text>Here is some text blah blah ...</message-text>
    </slide>
    <slide>
        <message-text>Invitation</message-text>
        <ical><url>http://www.yoursite.com/cal/2.ics</url></ical>
        <duration>10</duration>
    </slide>
</request>

Response Example: Success

Example: sendMMS Success Response
<response>
    <status>Success</status>
    <to>12399471613</to>
    <mms-id>35674</mms-id>
    <tracking-id>MMS_12345</tracking-id>
    <status-details>MMS request accepted and queued for delivery</status-details>
</response>

Response Example: Failure

Example: sendMMS Failure Response
<response>
    <status>Failure</status>
    <error-code>E111</error-code>
    <to>12399471613</to>
    <error-info>Invalid shortcode</error-info>
</response>

deleteMMSID

Overview
Deletes an MMS template whose mms-id is defined in the XML. All contents in the MMS template will be deleted immediately. In the case of Optimized MMS, the transcoded files will be also deleted.

Request Parameters:

Mandatory: action, api_key, mms-id

Response Parameters:

status, mmsId, errorCode, errorInfo

Related Error Codes:

E104, E105, E108, E112, E113, E120, E241, E620

Response Example

Example: deleteMMSID request
<request>
    <action>deleteMMSID</action>
    <api-key>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</api-key>
    <mms-id>35674</mms-id>
</request>

Request:Success

Example: deleteMMSID request Success
<response>
    <status>Success</status>
    <mms-id>35674</mms-id>
</response>

Request:Failure

Example: deleteMMSID request Failure
<response>
    <status>Failure</status>
    <error-code>E241</error-code>
    <error-info>Invalid mms-id / MMS do not exist</error-info>
</response>

getMMSTemplates

Overview
List all the previously created MMS templates (mms-ids) created using the saveMMS API. Note, deleted templates are not included in this listing. All the MMS templates will be listed in the descending order of date (i.e., latest to the oldest). If no “start-date” is specified in the API request then by default all mms templates are listed. The default “page-number” is taken as 1 whereas the default “items-per-page” is 100, if not specified. GMT/UTC timestamps are accepted for “start-date”.

Request Parameters:

Mandatory: action, api_key

Optional: start-date, page-number, items-per-page

Related Error Codes:

E104, E105, E108, E112, E113, E120, E212, E213, E214

Request Example:

Example: getMMSTemplates Request
<request>
    <action>getMMSTemplates</action>
    <api-key>qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ</api-key>
    <start-date>2014-03-31T11:30:00+00:00</start-date>
    <page-number>1</page-number>
    <items-per-page>3</items-per-page>
</request>

Response Example: Success

Example: getMMSTemplates Success Response
<response>
    <status>Success</status>
    <start-date>2014-03-31T11:30:00+00:00</start-date>
    <page-number>1</page-number>
    <items-per-page>3</items-per-page>
    <total-results>3</total-results>
    <mms-template>
         <mms-id>1234</mms-id>
         <mms-name>MMS-4</mms-name>
         <mms-subject>mms-test-4</mms-subject>
         <date-created>2014-10-31T09:30:00+00:00</date-created>
         <total-slides>2</total-slides>
         <mms-size>2048</mms-size>
    </mms-template>
    <mms-template>
         <mms-id>1233</mms-id>
         <mms-name>MMS-3</mms-name>
         <mms-subject>mms-test-3</mms-subject>
         <date-created>2014-10-30T19:00:00+00:00</date-created>
         <total-slides>4</total-slides>
         <mms-size>4096</mms-size>
    </mms-template>
    <mms-template>
         <mms-id>1230</mms-id>
         <mms-name>MMS-2</mms-name>
         <mms-subject>mms-test-2</mms-subject>
         <date-created>2014-10-30T08:30:00+00:00</date-created>
         <total-slides>2</total-slides>
         <mms-size>5126</mms-size>
    </mms-template>
</response>

Response Example: Failure

Example: getMMSTemplates Failure Response
<response>
    <status>Failure</status>
    <error-code>E214</error-code>
    <error-info>start-date is invalid</error-info>
</response>

Mblox Postbacks

MMS MT Delivery Report Postbacks Overview
The MMS MT postback API notifies you of the delivery status of each message you send. There are two methods for delivering content; Binary and HTML. Following are postback notification formats depending on which method is used.

MMS MT Postback Types:

MMS MT Delivery Status A postback notification called N101 is immediately sent after we begin to process the MMS. Upon receiving Delivery Report (DLR) from the carrier, the system generates postback notification N102 with the handset information. The N101 and N102 notifications are linked by tracking-id.

When the mobile network operator does not support MMS or the destination handset does not support the size of the content within the MMS, in case of Optimized MMS we fall back to SMS/HTML to deliver the message. In this method we deliver the MMS as an SMS containing a link to an HTML page with the content.

The fallback-sms-text is included in the SMS message text. The possible MMS status code that you may receive for the delivery status is one of following: N101, N102, E101, E102.

If you specified to send a Device Discovery Message then you may receive one of the following status codes regarding the delivery status of the Device Discovery Message: N501, N502, E501, E502.

Variable Description
origin The notification origin, for example, MMS_MT means an MMS terminated on a mobile.
code The postback notification code.
sent-as Indicates if the MMS was delivered as MMS (binary) or SMS (HTML).
mms-id Id of the MMS Template.
status For N101 and N501, notification status can be “Message Sent”.
For N102 and N502, notification status can be “Message Sent/Delivered”.
For E101 and E501, notification status can be “Message Failed”.
For E102 and E502, notification status can be “Message Sent/Expired”, “Message Sent/Rejected”, “Message Sent/Failed” or “Message Sent/Not Supported”.
from The shortcode the message is sent from
handset Handset profile returned inside Delivery Receipt. This is present only in N102 notification.
to The recipient of the message.
tracking-id The ID to correlate API requests, and delivery receipts.
operator-id Carrier Identification.
timestamp The timestamp the MMS was sent (N101) or when the MMS was delivered (N102).
status-details Any additional information passed back from the carrier.

Postback Schema

N101 Example: (Binary)
<postback>
    <origin>MMS_MT</origin>
    <code>N101</code>
    <sent-as>MMS</sent-as>
    <status>Message Sent</status>
    <mms-id>39597</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3OQ==</tracking-id>
    <operator-id>31003</operator-id>
    <timestamp>2014-06-07T07:27:29-05:00</timestamp>
</postback>
N101 Example: (HTML)
<postback>
    <origin>MMS_MT</origin>
    <code>N101</code>
    <sent-as>SMS</sent-as>
    <status>Message Sent</status>
    <mms-id>39755</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3Nw==</tracking-id>
    <operator-id>31004</operator-id>
    <timestamp>2014-06-07T07:27:34-05:00</timestamp>
    <status-details>Handset setting: mms with pass via HTML</status-details>
</postback>
N102 Example: (Binary)
<postback>
    <origin>MMS_MT</origin>
    <code>N102</code>
    <sent-as>MMS</sent-as>
    <status>Message Sent/Delivered</status>
    <mms-id>39597</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3OQ==</tracking-id>
    <operator-id>31003</operator-id>
    <timestamp>2014-06-07T07:27:34-05:00</timestamp>
    <handset>moto17c</handset>
</postback>
N102 Example: (HTML)
<postback>
    <origin>MMS_MT</origin>
    <code>N102</code>
    <sent-as>SMS</sent-as>
    <status>Message Sent/Delivered</status>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3Nw==</tracking-id>
    <operator-id>31004</operator-id>
    <timestamp>2014-06-07T07:28:09-05:00</timestamp>
</postback>
E101 Example: When the system is unable to send an MMS we return a postback E101
<postback>
    <origin>MMS_MT</origin>
    <code>E101</code>
    <status>Message Failed</status>
    <mms-id>39755</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3Nw==</tracking-id>
    <operator-id>31004</operator-id>
    <status-details>Error fetching dynamic content</status-details>
</postback>
E102 Example: When the MMS delivery fails due to various reasons we return a postback E102
<postback>
    <origin>MMS_MT</origin>
    <code>E102</code>
    <status>Message Sent/Rejected</status>
    <mms-id>39755</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3Nw==</tracking-id>
    <operator-id>31004</operator-id>
    <status-details>Recipient blocked by mobile operator</status-details>
</postback>
N501 Example
<postback>
    <origin>MMS_MT</origin>
    <code>N501</code>
    <sent-as>MMS</sent-as>
    <status>Message Sent</status>
    <mms-id>39755</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3Nw==</tracking-id>
    <operator-id>31004</operator-id>
    <timestamp>2014-06-07T07:27:34-05:00</timestamp>
    <status-details></status-details>
</postback>
N502 Example
<postback>
    <origin>MMS_MT</origin>
    <code>N502</code>
    <sent-as>MMS</sent-as>
    <status>Message Sent/Delivered</status>
    <mms-id>39597</mms-id>
    <from>28444</from>
    <to>12399471613</to>
    <tracking-id>TU1TXzU5Nzg3OQ==</tracking-id>
    <operator-id>31003</operator-id>
    <timestamp>2014-06-07T07:27:34-05:00</timestamp>
    <handset>moto17c</handset>
</postback>

saveMMS Encoding status

When MMS is saved, we generate postback notification. When saving and encoding of the content is successful we generate N003. If encoding of the content failed we generate postback E002 containing mms-id and audio-name/video-name pointing to the content that failed to encode properly. When E002 is returned the mms-id should be considered corrupted. Note: The image-name is not included since image encoding is not supported.

Variable Description
code N003 or E002 based on the success of the content coding.
origin MMS_MT for saving MMS content.
mms-id ID of the MMS.
audio-name URL to audio content that failed to encode properly.
video-name URL to video content that failed to encode properly.
N003 (Save MMS Successful) Example
<postback>
    <origin>MMS_MT</origin>
    <code>N003</code>
    <mms-id>35674</mms-id>
</postback>
E002 (Save MMS Failure) Example
<postback>
    <origin>MMS_MT</origin>
    <code>E002</code>
    <mms-id>35674</mms-id>
    <audio-name>http://www.yoursite.com/audio/1.mp3</audio-name>
</postback>

Mblox MMS MO Postbacks

Note: MO MMS functionality is limited to Verizon, Sprint and T-Mobile initially. MO MMS for AT&T will be supported shortly after commercial launch.

The MMS MO postback API notifies you that a customer has replied to your message, or interacted to one of your keywords.

MMS MO Information: To receive MMS MO postback you need to work with your Mblox Account Manager to provision with your account. Once the MMS MO postback is enabled you will start receiving postbacks for each MMS MO received on the MMS MO Keyword or Short Code.

The MMS MO This postback notifies you when an MMS MO is received

Variable Description
code N401.
origin MMS_MO.
from The phone number, including the country code of the sender.
to The recipient shortcode.
keyword If a keyword was recognized in the first word of the subject or the first word body of the message and it matched to a MMS Inbox Keyword campaign that keyword will be passed in this node.
tracking-id A tracking ID, Mblox has assigned this message.
operator-id The operator-id of the sender’s carrier.
timestamp The timestamp that our system received the MMS MO.
message-subject The subject sent in the MMS MO.
content Contains the file nodes sent in the MMS MO.
file A series of sub-nodes that contains a single URL to a picture, video, audio or text file sent in the MMS MO within each node. The URL points to the location of the content on our servers. For those developing the back-end handling of the postback URL, you may choose to download/store these content files for whatever purpose you see fit. You may also choose to store the URLs for download at a future time. The file will be removed based on the terms of your contract.
MMS MO Example
<postback>
    <origin>MMS_MO</origin>
    <code>N401</code>
    <from>14082257140</from>
    <to>28444</to>
    <keyword>all</keyword>
    <tracking-id>MMS_MO_iLnCRrL6</tracking-id>
    <operator-id>31002</operator-id>
    <timestamp>2014-02-03T11:19:49-05:00</timestamp>
    <message-subject></message-subject>
    <content>
        <file>URL of Content Here</file>
        <file>URL of Content Here</file>
        <file>URL of Content Here</file>
    </content>
</postback>

Appendix

Error Code Reference

Code Description
E100 Invalid request, please meke a valid XML Post request.
E104 Authentication failed, Invalid api-key.
E105 No API access to this user.
E106 Time interval between each API call should be at least X seconds.
E107 Invalid action. This api user is not allowed to use this action
E108 Invalid XML. XML parsing failed.
E110 Invalid ‘to’ / receiver number.
E111 Invalid 'from’ / shortcode.
E112 IP was not whitelisted. API call rejected.
E113 Exceeded the allowed throughput for this API action.
E114 Phone number is blacklisted. API call rejected.
E212 page-number is invalid.
E213 items-per-page is invalid
E214 start-date is invalid.
E223 More than one object is not allowed in the same slide.
E224 MMS audio/video/image are not allowed with object in the same slide.
E225 Exceeded number of slides allowed for the MMS.
E226 MMS audio / video are not allowed in the same slide.
E227 MMS video / image are not allowed in the same slide.
E228 MMS text cannot exceed X characters.
E229 Content not allowed.
E230 Invalid / bad slide duration in slide X.
E241 Invalid mms-id / MMS do not exist.
E311 Invalid MMS name / name is required.
E312 No slides.
E313 Slide X is empty.
E314 Invalid message-subject / message-subject is required.
E331 Image in slide X is too big.
E332 Audio in slide X is too big.
E333 Video in slide X is too big.
E334 Text in slide X is too long.
E335 vCard in slide X is too big.
E336 iCal in slide X is too big.
E337 PDF in slide X is too big.
E338 Passbook file in slide X is too big.
E341 Image file in slide X is corrupted.
E351 Could not copy Image in slide X.
E352 Could not copy Audio in slide X.
E353 Could not copy Video in slide X.
E355 Could not copy vCard in slide X.
E356 Could not copy iCal in slide X.
E357 Could not copy PDF in slide X.
E358 Could not copy Passbook file in slide X.
E618 Carrier lookup failed. Please retry.
E619 Carrier not provisioned.
E620 mms-id is required.
E622 fallback-sms-text is required.
E626 MMS not available. Encoding in progress, try again later.
E627 Invalid service-id / service-id is required.
E628 Mobile operator / carrier not supported.
E629 Unrecognized content type.
E650 Invalid operator-id / operator-id is required.
E651 Invalid operator-id / operator-id not found in the system.

Postback Notification Codes

Code Description
E100 Invalid request, please meke a valid XML Post request.
E002 Encoding of MMS audio failed. (saveMMS function)
E003 Encoding of MMS video failed. (saveMMS function)
E012 Encoding of MMS audio failed. (sendMMS function)
E013 Encoding of MMS video failed. (sendMMS function)
E101 Error occurred. Impossible to send MMS.
E102 Error occurred. MMS Delivery was not successful.
E202 Error occured. MMS as SMS Delivery was not successful.
E501 Error occurred. Impossible to send DDM Message.
E502 Error occurred. DDM Delivery was not successful.
E999 Post Message Sending Queue Processing Errors.
N101 Notification that MMS was sent.
N102 Notification that MMS status was updated.
N202 Notification that MMS was delivered as SMS.
N401 MMS MO received successfully.
N501 Notification that Device Discovery Message is sending.
N502 Notification that Device Discovery Message delivery status has changed.
E002 Encoding of MMS audio failed. (saveMMS function)
E003 Encoding of MMS video failed. (saveMMS function)
E012 Encoding of MMS audio failed. (sendMMS function)
E013 Encoding of MMS video failed. (sendMMS function)
E101 Error occurred. Impossible to send MMS.
E102 Error occurred. MMS Delivery was not successful.
E202 Error occured. MMS as SMS Delivery was not successful.
E501 Error occurred. Impossible to send DDM Message.
E502 Error occurred. DDM Delivery was not successful.
E999 Post Message Sending Queue Processing Errors.
N101 Notification that MMS was sent.
N102 Notification that MMS status was updated.
N202 Notification that MMS was delivered as SMS.
N401 MMS MO received successfully.
N501 Notification that Device Discovery Message is sending.
N502 Notification that Device Discovery Message delivery status has changed.