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.

Select your MM7 version below to see the version-specific parameters and sample requests.

MM7 5.5.0

🚧

Double-check your version

Vibes supports MM7 protocol for multiple versions of MM7, so be sure you’re referencing the correct MM7 version before you get started.

Skip to MM7 6.8.0.

Example 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.

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.5.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

ElementRequired?Description
TransactionIDYesThe 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.
MM7VersionNo5.3.0

The MM7Version should be set to 5.3.0 because of a bug in the 5.5.0 XSD.
VASPIDNoNot used. Authentication is based on the Authorization header value.
VASIDNoNot used. Authentication is based on the Authorization header value.
SenderAddressYesThe code that is sending the outgoing MMS. This value is required by the Vibes MMSC (even though the specification says it is optional).
RecipientsYesThe 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 not supported.

The displayOnly flag will not be used because the Vibes MMSC only allows one recipient per message.
ServiceCodeNoNot supported, do not set.
LinkedIDNoNot supported, do not set.
MessageClassNoThe type of message. The allowed values are:
Personal
Informational
Advertisement
Auto
Informational is the default.
TimestampNoNot supported, do not set.
ReplyChargingNoNot supported, do not set.
EarliestDeliveryTimeNoNot supported, do not set.
ExpiryDateNoNot supported, do not set.
DeliveryReportNoFlag 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.
ReadReplyNoFlag 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.
PriorityNoThe importance of the message: Normal, High, or Low.
SubjectNoFree text to be displayed as the title of the message on the handset.
ChargedPartyNoNot supported, do not set.
DistributionProtectionNoThe 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.
ContentYesThis value is required by the Vibes MMSC (even though the spec says it's optional).
hrefNoA String reference to the content contained within the message.
Formatted: "cid:<filename>"
allowAdaptationsNoAllow the content to be adapted for the phone by the carrier MMSC. This is set to false by default.

Example Response

Below is an example of a successful response to a MM7 call. 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-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>

Elements of a Response

ElementRequired?Description
TransactionIDYesThe transactionID associated with the message from the submit request.
MessageIDYesIf 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.
MM7VersionYes5.3.0

The MM7Version should be set to 5.3.0 because of a bug in the 5.5.0 XSD.
StatusCodeYesA numeric code indicating the result of the request.
StatusTextYesA free-text description of the result of the request.
DetailsNoOptional free text that may be included to further describe the result of the request.

MM7 6.8.0

🚧

Double-check your version

Vibes supports MM7 protocol for multiple versions of MM7, so be sure you’re referencing the correct MM7 version before you get started.

Skip to MM7 5.5.0.

Example Request

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

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--

Elements & Attributes of a Request

ElementRequired?Description
TransactionIDYesThe transactionID associated with the message. Making this unique per request should help with the request tracking within the system.
\@mustUnderstand should be set to 1.
\@actor and \@encodingStyle should not be set.
MM7VersionNo6.8.0
VASPIDNoNot used. Authentication is based on the Authorization header value.
VASIDNoNot used. Authentication is based on the Authorization header value.
SenderAddressYesThe code that is sending the MT MMS message. This value is required by the Vibes MMSC (even though the specification says it is optional).

The shortcode should be wrapped in a <ShortCode> element.
RecipientsYesThe 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 not supported.
The displayOnly flag will not be used because the Vibes MMSC only allows one recipient per message.
ServiceCodeNoNot supported. Do not set.
LinkedIDNoNot supported. Do not set.
MessageClassNoThe type of message. The allowed values are:
Personal
Informational
Advertisement
Auto
Informational is the default.
TimestampNoNot supported. Do not set.
ReplyChargingNoNot supported. Do not set.
EarliestDeliveryTimeNoNot supported. Do not set.
ExpiryDateNoNot supported. Do not set.
DeliveryReportNoFlag to request delivery reports for this MT 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 not, the entire request will be rejected.
ReadReplyNoFlag 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. It defaults to false.
PriorityNoThe importance of the message: Normal, High, or Low.
SubjectNoFree text to be displayed as the title of the message on the handset.
ChargedPartyNoNot supported. Do not set.
ChargedPartyIDNoNot supported. Do not set.
DistributionIndicatorNoThe 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.
DeliveryConditionNoNot supported. Do not set.
ApplicIDNoIdentification information for the destination application on the handset. If set, this information will be passed through to the carrier.
ReplyApplicIDNoIdentification information for the application which will handle delivery reports, read-reply reports and reply-MMS. If set, this information will be passed through to the carrier.
AuxApplicInfoNoAdditional application/implementation specific control information. If set, this information will be passed through to the carrier.
ContentClassNoClassification information for the message content. If set, this information will be passed through to the carrier.
The possible values are: text, image-basic, image-rich, video-basic, video-rich, megapixel, content-basic, content-rich.
DRMContentNoThe Boolean flag indicating if the content of the message is DRM protected.
ContentYesThis value is required by the Vibes MMSC (even though the spec says its optional).
hrefNoA String reference to the content contained within the message.
Formatted: "cid:<filename>"
allowAdaptationsNoAllow the content to be adapted for the phone by the carrier MMSC. This is set to true by default.

Example Response

Below is an example of a successful response to a MM7 call. 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>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 a 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

ElementRequired?Description
TransactionIDYesThe transactionid associated with the message from the submit request.
MessageIDYesIf 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.
MM7VersionNo6.8.0
StatusCodeYesA numeric code indicating the result of the request.
StatusTextYesA free-text description of the result of the request.
DetailsNoOptional free text that may be included to further describe the result of the request.
Language
Authorization
Basic
base64
:
Click Try It! to start a request and see the response here!