API Reference
Start typing to search…

Send MMS

post https://messageapi-mms.vibesapps.com/mms/mm7/submit

To send an MMS message to a mobile device, you’ll utilize MM7 protocol, the industry standard protocol for sending MMS messages. The MM7 protocol is a SOAP-based protocol.

❗️

Code with caution

SOAP-based protocols are highly dependent on formatting of your calls. If you are not familiar with SOAP calls, we recommend using cURL to make the call and using our executable code samples, and use these as a starting point to build your requests.

Authorization Header

Just like with the HTTP SMS protocols, sending an MMS message requires you to include basic authentication. This header must be present for all requests. For more information, please refer to the section on Authentication.

Custom Headers

In addition to the basics, Vibes protocol further customizes the MM7 experience with a few custom headers, which allow the user more security and customization in their MMS send.

HeaderDescription
X-Vibes-CarrierCodeThe Vibes Carrier Code, if known, otherwise the carrier is looked up.
X-Vibes-DlrCallbackUrlThe URL to which Delivery Reports should be sent.

Delivery Report Request Options

The table below specifies how the Multimedia Message Service Center (MMSC) would process the various Delivery Report request options.

X-Vibes-DlrCallbackUrl Header SetX-Vibes-DlrCallbackUrl Header Not Set
Delivery ReportFlag Set to trueDelivery Reports will be requested from the carrier, and any final status report returned from the carrier is sent to the Callback URL.Delivery Reports are requested from the carrier but no callbacks are sent to the client.
Delivery ReportFlag Set to falseThe status of delivery of the message to carrier is returned to the Callback URL. Delivery Reports are not requested from the carrier.Delivery reports are not requested from the carrier and no callbacks are sent to the client.

Requests and Responses

The request body has a maximum total size of 1 MB. Requests with larger bodies will result in a 413 Entity Too Large error. Note that due to MIME/base64 encoding the request body will be larger than the binary media. File size can also affect performance; we recommend requests under 300 KB.
Vibes supports MM7 protocol for multiple versions of MM7, so be sure you’re referencing the correct MM7 version before you get started.

Request

Below is an example of an XML call that uses the MM7 SOAP protocol to send a message with a gif attachment. The elements are defined below.

****
 ****
  ****
  ****
  CHOOSE YOUR MM7 VERSION BY SELECTING THE CORRESPONDING TAB ABOVE
  ****
  ****
 ****
****
POST /mms/mm7/submit HTTP/1.1
SOAPAction:
Authorization: Basic Y2xpZW50QHZpYmVzLmNvbTpwYXNzd29yZA==
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 127.0.0.1:8081
Content-Length: 47384
Content-Type: multipart/related; type="text/xml"; boundary=MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c; start="<[email protected]>"
X-Vibes-CarrierCode: 102
  
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-ID: <[email protected]>
 
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">ea92fdc3-44e9-466a-9c40-f51a704a2590</TransactionID>
    </soapenv:Header>
    <soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
        <ns3:SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
            <ns3:MM7Version>5.3.0</ns3:MM7Version>
            <ns3:SenderIdentification>
                <ns3:SenderAddress>
                    <ns3:ShortCode>63901</ns3:ShortCode>
                </ns3:SenderAddress>
            </ns3:SenderIdentification>
            <ns3:Recipients>
                <ns3:To>
                    <ns3:Number>+13127536330</ns3:Number>
                </ns3:To>
            </ns3:Recipients>
            <ns3:DeliveryReport>true</ns3:DeliveryReport>
            <ns3:Subject>Hello Vibes</ns3:Subject>
            <ns3:Content href="cid:attachment.cid"/>
        </ns3:SubmitReq>
    </soapenv:Body>
</soapenv:Envelope>
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: multipart/mixed;  boundary="----=_Part_1_735700397.1414682699327"
Content-Transfer-Encoding: binary
Content-ID: <attachment.cid>
  
------=_Part_1_735700397.1414682699327
Content-Type: image/gif; name=sample.gif
Content-Disposition: attachment; filename=sample.gif
Content-ID: <sample.gif>
  
GIF89aÔÔ ...
------=_Part_1_735700397.1414682699327
Content-Type: text/plain; name=Simple.txt
Content-Disposition: attachment; filename=Simple.txt
Content-ID: <Simple.txt>
  
Simple text as an attachment ...
------=_Part_1_735700397.1414682699327--
  
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c--
POST /mms/mm7/submit HTTP/1.1
SOAPAction:
Authorization: Basic Y2xpZW50QHZpYmVzLmNvbTpwYXNzd29yZA==
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 127.0.0.1:8081
Content-Length: 47384
Content-Type: multipart/related; type="text/xml"; boundary=MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c; start="<[email protected]>"
X-Vibes-CarrierCode: 102
  
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-ID: <[email protected]>
 
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header>
        <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">ea92fdc3-44e9-466a-9c40-f51a704a2590</TransactionID>
    </soapenv:Header>
    <soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
        <ns3:SubmitReq xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">
            <ns3:MM7Version>6.8.0</ns3:MM7Version>
            <ns3:SenderIdentification>
                <ns3:SenderAddress>
                    <ns3:ShortCode>63901</ns3:ShortCode>
                </ns3:SenderAddress>
            </ns3:SenderIdentification>
            <ns3:Recipients>
                <ns3:To>
                    <ns3:Number>+13127536330</ns3:Number>
                </ns3:To>
            </ns3:Recipients>
            <ns3:DeliveryReport>true</ns3:DeliveryReport>
            <ns3:Subject>Hello Vibes</ns3:Subject>
            <ns3:Content href="cid:attachment.cid"/>
        </ns3:SubmitReq>
    </soapenv:Body>
</soapenv:Envelope>
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c
Content-Type: multipart/mixed;  boundary="----=_Part_1_735700397.1414682699327"
Content-Transfer-Encoding: binary
Content-ID: <attachment.cid>
  
------=_Part_1_735700397.1414682699327
Content-Type: image/gif; name=sample.gif
Content-Disposition: attachment; filename=sample.gif
Content-ID: <sample.gif>
  
GIF89aÔÔ ...
------=_Part_1_735700397.1414682699327
Content-Type: text/plain; name=Simple.txt
Content-Disposition: attachment; filename=Simple.txt
Content-ID: <Simple.txt>
  
Simple text as an attachment ...
------=_Part_1_735700397.1414682699327--
  
--MIMEBoundary_22efcfd39d40f1e286128d53c1fe240ba31d19c88ba31f5c--

Elements & Attributes of a Request

Element

Required

Description

TransactionID

Yes

The transactionID associated with the message, which is defined by the user. Making this unique per request should help with the request tracking within the system.

MM7Version

No

FOR MM7 5.5.0: 5.3.0 The MM7Version should be set to 5.3.0 because of a bug in the 5.5.0 XSD.

FOR MM7 6.8.0: 6.8.0

VASPID

No

Not used. Authentication is based on the Authorization header value.

VASID

No

Not used. Authentication is based on the Authorization header value.

SenderAddress

Yes

The code that is sending the outgoing MMS. This value is required by the Vibes MMSC (even though the specification says it is optional).

Recipients

Yes

The Mobile Directory Number (MDN) to deliver the MMS to. The MDN can be formatted as 10 digit, 11 digit, or E.164 format.
The MDN should be wrapped in a <Number> element. The <Number> element should be wrapped in a <To> element. Multiple MDNs are not supported. The <CC> and <Bcc> elements are also not supported. The displayOnly flag will not be used because the Vibes MMSC only allows one recipient per message.

ServiceCode

No

Not supported, do not set.

LinkedID

No

Not supported, do not set.

MessageClass

No

The type of message. The allowed values are:
Personal Informational Advertisement Auto

Informational is the default.

Timestamp

No

Not supported, do not set.

ReplyCharging

No

Not supported, do not set.

EarliestDeliveryTime

No

Not supported, do not set.

ExpiryDate

No

Not supported, do not set.

DeliveryReport

No

Flag to request delivery reports for this outgoing MMS message.

If true, DeliveryReportReq callback requests will be posted to the client-specified URL sometime after the request has been received for any Delivery Receipts received from the carrier. It defaults to  false.

If this flag is set to true, then the X-Vibes-DlrCallbackUrl custom header should have the URL to which Delivery Reports should be sent. If it does not, the whole request will be rejected.

ReadReply

No

Flag to request read replies. If true, at least one ReadReplyReq request will be posted to the client-specified URL sometime after the request has been received. Defaults to false.

Priority

No

The importance of the message: Normal, High, or Low.

Subject

No

Free text to be displayed as the title of the message on the handset.

ChargedParty

No

Not supported, do not set.

DistributionProtection

No

The flag on whether to allow message forwarding from the phone. If set to true, the message will not be able to be forwarded. Defaults to false.

Content

Yes

This value is required by the Vibes MMSC (even though the spec says it's optional).

href

No

A string reference to the content contained within the message.
Formatted: "cid:<filename>"

allowAdaptations

No

Allow the content to be adapted for the phone by the carrier MMSC. This is set to false by default.

Response

Below is an example of a successful response to a MM7 call. The elements are defined below.

****
 ****
  ****
  ****
  CHOOSE YOUR MM7 VERSION BY SELECTING THE CORRESPONDING TAB ABOVE
  ****
  ****
 ****
****
<?xml version=“1.0” encoding=“UTF-8"?>
<soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope/”>
   <soapenv:Header>
      <TransactionID xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2”>ea92fdc3-44e9-466a-9c40-f51a704a2590</TransactionID>
   </soapenv:Header>
   <soapenv:Body xmlns:ns3=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2”>
      <ns3:SubmitRsp xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2”>
         <ns3:MM7Version>5.3.0</ns3:MM7Version>
         <ns3:Status>
            <ns3:StatusCode>1000</ns3:StatusCode>
            <ns3:StatusText>Success</ns3:StatusText>
         </ns3:Status>
         <ns3:MessageID>d95c7ccb-4fbd-4b48-b70c-fadc5ff225b5</ns3:MessageID>
      </ns3:SubmitRsp>
   </soapenv:Body>
</soapenv:Envelope> 
<?xml version=“1.0” encoding=“UTF-8"?>
<soapenv:Envelope xmlns:soapenv=“http://schemas.xmlsoap.org/soap/envelope/”>
   <soapenv:Header>
      <TransactionID xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4”>16d105f4-9b86-4b8a-bdf5-9b02e2795fd6-1</TransactionID>
   </soapenv:Header>
   <soapenv:Body xmlns:ns3=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4”>
      <ns3:SubmitRsp xmlns=“http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4”>
         <ns3:MM7Version>6.8.0</ns3:MM7Version>
         <ns3:Status>
            <ns3:StatusCode>1000</ns3:StatusCode>
            <ns3:StatusText>Success</ns3:StatusText>
         </ns3:Status>
         <ns3:MessageID>57df0722-28f1-49e9-aa85-626919b5b888</ns3:MessageID>
      </ns3:SubmitRsp>
   </soapenv:Body>
</soapenv:Envelope>

Below is an example of a response to an MM7 call that returned an error. The elements are defined below.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <TransactionID xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">16d105f4-9b86-4b8a-bdf5-9b02e2795fd6-1</TransactionID>
   </soapenv:Header>
   <soapenv:Body xmlns:ns3="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
      <ns3:SubmitRsp xmlns="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4">
         <ns3:MM7Version>6.8.0</ns3:MM7Version>
         <ns3:Status>
            <ns3:StatusCode>2002</ns3:StatusCode>
            <ns3:StatusText>SenderAddress value 'YOUR_SHORTCODE' invalid, Reason: Invalid SenderAddress</ns3:StatusText>
         </ns3:Status>
      </ns3:SubmitRsp>
   </soapenv:Body>
</soapenv:Envelope>

Elements of a Response

Element

Required

Description

TransactionID

Yes

The transactionid associated with the message from the submit request.

MessageID

Yes

If the request was successful, this element will contain the unique identifier generated by the Vibes MMSC for the message. This ID should be stored for future reference.

MM7Version

Yes

FOR MM7 5.5.0: 5.3.0 The MM7Version will be set to 5.3.0 because of a bug in the 5.5.0 XSD.

FOR MM7 6.8.0: 6.8.0

StatusCode

Yes

A numeric code indicating the result of the request.

StatusText

Yes

A free-text description of the result of the request.

Details

No

Optional free text that may be included to further describe the result of the request.

Language
Credentials
Basic
base64
:
Click Try It! to start a request and see the response here!