MMS Pack

MMS Pack

Bundle of pre-paid MMS

Buy product
Included in the SAPO Services SDK

Technical Overview

SendMessage Service

With this API you can send MMS messages (including text, image, sound and video) to one or more recipients (e.g. to mobile terminals).

This API is based on the OneAPI v1.0 MMS specification defined by GSMA. It implements the OneAPI SendMessage interface as a SOAP 1.1 and Soap with Attachments (SwA) service (we also support a non-SwA interface).

MessageNotification Service

The MMS delivery status change notifications are sent to this interface.

This service is implemented by the client application. Its URI is defined on the sendMessage operation.

SendMessageInlineAttachments Service

Send MMS messages with inline attachments (the is complementary to the OneAPI/MMS/SendMessage service, which expects the attachments in a Soap with Attachments body).

API Reference

Download Service WSDL Contract
Service Operation Description
MessageNotification notifyMessageDeliveryReceipt

Called when an previously sent MMS (with sendMessage or sendMessageWithInlineAttachments) has changed state.
SendMessage getMessageDeliveryStatus

Obtains the delivery state of a sent MMS message.

This is an alternative to the notification service.
sendMessage

Sends a MMS message to one or more recipients. Optionally, it can notify an endpoint when there is a delivery state change.

This uses SwA; for non SwA use the SendMessageInlineAttachments service.
SendMessageInlineAttachments sendMessageWithInlineAttachments

Sends a MMS message to one or more recipients. Optionally, it can notify an endpoint when there is a delivery state change.

You can send text, image, sound and video; see the supported media types.

SendMessage Service

getMessageDeliveryStatus

Obtains the delivery state of a sent MMS message.

This is an alternative to the notification service.

Request Parameters

requestIdentifier : string (required)

The request identifier of a sent MMS message.

This is the result value returned by the sendMessage operation.

Response Parameters

result : DeliveryInformation (optional)

The delivery status.

Delivery status of a sent MMS message

The following example shows how to obtain the delivery status of a sent MMS message.

And the corresponding, successful, response:

Go to top

sendMessage

Sends a MMS message to one or more recipients. Optionally, it can notify an endpoint when there is a delivery state change.

This uses SwA; for non SwA use the SendMessageInlineAttachments service.

Request Parameters

addresses : anyURI (required)

A list of one or more destination telephone addresses.

An address is a URI of the form tel:full-address, where full-address is an international (including country code) telephone number, e.g. tel:+351213456789 (E.164 format).

senderAddress : string (optional)

The sender name.

Although this parameter name has "address" in its name, you can use almost any string (this field is restricted add link to restrictions).

subject : string (optional)

The MMS subject.

priority : MessagePriority (optional)

The message priority.

charging : ChargingInformation (optional)

Do not pass this parameter, or set it to null. Its not used by our implementation.

receiptRequest : SimpleReference (optional)

Defines the endpoint that should be notified when the delivery state has changed, e.g. when the message has been delivered to the terminal.

format : MessageFormat (optional)

The message format.

Currently, only MMS is supported.

Response Parameters

result : string (required)

The request identifier of the sent MMS message.

Send MMS with receipt notification

The following example shows how to send an MMS and receive a notification when its delivery status changes (e.g. when it's delivered to the user terminal).

And the corresponding, successful, response:

When the MMS is delivered to the terminal, the application will receive the following notification message:

Go to top

SendMessageInlineAttachments Service

sendMessageWithInlineAttachments

Sends a MMS message to one or more recipients. Optionally, it can notify an endpoint when there is a delivery state change.

You can send text, image, sound and video; see the supported media types.

Request Parameters

addresses : anyURI (required)

A list of one or more destination telephone addresses.

An address is a URI of the form tel:full-address, where full-address is an international (including country code) telephone number, e.g. tel:+351213456789 (E.164 format).

senderAddress : string (optional)

The sender name.

Although this parameter name has "address" in its name, you can use almost any string (this field is restricted add link to restrictions).

subject : string (optional)

The MMS subject.

priority : MessagePriority (optional)

The message's priority.

charging : ChargingInformation (optional)

Do not pass this parameter, or set it to null. It's not used by our implementation.

receiptRequest : SimpleReference (optional)

Defines the endpoint that should be notified when the delivery state has changed, e.g. when the message has been delivered to the terminal.

format : MessageFormat (optional)

The message format.

Currently, only MMS is supported.

attachments : Attachments (required)

A list of attachments.

Response Parameters

result : string (required)

Send MMS with attachments

The following example shows how to send a MMS message (text and image).

You can also define the receiptRequest; see the example at the regular sendMessage operation.

And the corresponding, successful, response:

Go to top

MessageNotification Entities

DeliveryInformation

The message's delivery status sent to a specific destination address.

Attribute Name Description
address : anyURI The destination address. e.g. tel:+351213456789.
deliveryStatus : DeliveryStatus The delivery status.
description : string (optional) The delivery status description.
Go to top

DeliveryStatus

The message's delivery status.

Value Name Description
DeliveredToTerminal Successful delivery to Terminal.
DeliveryUncertain Delivery status unknown. e.g. because it was handed off to another network.
DeliveryImpossible Unsuccessful delivery. The message could not be delivered before it expired.
MessageWaiting The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
DeliveredToNetwork Successful delivery to the network enabler responsible for routing the message.
DeliveryNotificationNotSupported Unable to provide delivery receipt notification.
Go to top

SendMessage Entities

ChargingInformation

This entity is not supported by our implementation. Do not use.

Attribute Name Description
List of description : string
currency : string (optional)
amount : decimal (optional)
code : string (optional)
Go to top

DeliveryInformation

The message's delivery status sent to a specific destination address.

Attribute Name Description
address : anyURI The destination address. e.g. tel:+351213456789.
deliveryStatus : DeliveryStatus The delivery status.
description : string (optional) The delivery status description.
Go to top

DeliveryStatus

The message's delivery status.

Value Name Description
DeliveredToTerminal Successful delivery to Terminal.
DeliveryUncertain Delivery status unknown. e.g. because it was handed off to another network.
DeliveryImpossible Unsuccessful delivery. The message could not be delivered before it expired.
MessageWaiting The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
DeliveredToNetwork Successful delivery to the network enabler responsible for routing the message.
DeliveryNotificationNotSupported Unable to provide delivery receipt notification.
Go to top

MessageFormat

The message format.

The only supported format is MMS.

Value Name Description
MMS

The message is an MMS message.

This is the only supported format.
WapPush
SMS
EMS
SmartMessaging
IM
IMPagerMode
IMLargeMessage
IMFileTransfer
EMail
Go to top

MessagePriority

The message's priority. You should use the Default value.

Value Name Description
Default Default
Low Low
Normal Normal
High High
Go to top

SimpleReference

Attribute Name Description
endpoint : anyURI

The URI for the application HTTP endpoint that will receive the delivery notifications.

The exact type of the endpoint interface is choosen with the interfaceName member.
interfaceName : string

The endpoint interface name. Currently set this to soap (your application must implement the Notification interface).
correlator : string

An opaque value defined by your application. It was defined when you called the sendSms operation. It will be sent for the application notification endpoint as a callback context.
Go to top

SendMessageInlineAttachments Entities

Attachment

List of attachments.

Attribute Name Description
id : string

The content-id of this attachment.
type : string

The attachment media type (text, image, audio or video).

Given the wide range of mobile terminals available on the market you should use the recommended media types described below.

Media Type Recommended Media Type Notes
text text/plain Text.
image image/png, image/jpeg, image/gif Image.
audio audio/wav, audio/midi, audio/amr Audio.
video video/3gpp, video/mp4 Video.
body : base64Binary

The attachment contents (base64 encoded).
Go to top

Attachments

List of attachments.
Attribute Name Description
List of attachment : Attachment (optional)
Go to top

ChargingInformation

This entity is not supported by our implementation. Do not use.

Attribute Name Description
List of description : string
currency : string (optional)
amount : decimal (optional)
code : string (optional)
Go to top

MessageFormat

The message format.

The only supported format is MMS.

Value Name Description
MMS

The message is an MMS message.

This is the only supported format.
WapPush
SMS
EMS
SmartMessaging
IM
IMPagerMode
IMLargeMessage
IMFileTransfer
EMail
Go to top

MessagePriority

The message's priority. You should use the Default value.

Value Name Description
Default Default
Low Low
Normal Normal
High High
Go to top

SimpleReference

Attribute Name Description
endpoint : anyURI

The URI for the application HTTP endpoint that will receive the delivery notifications.

The exact type of the endpoint interface is choosen with the interfaceName member.
interfaceName : string

The endpoint interface name. Currently set this to soap (your application must implement the Notification interface).
correlator : string

An opaque value defined by your application. It was defined when you called the sendSms operation. It will be sent for the application notification endpoint as a callback context.
Go to top

SOAP API Authentication

Authenticating SOAP Request

Every request must contain authentication information to establish the identity of whom making the request and a autorization token called ESB Access Key.

ESB Access Key

Correct with the path to the access key

The ESB Access Key is what will authorize the usage of the API and is available when the buying process ends. In the costumer area you can find the product details where you can generate an ESB Access Key for you usage, another user registered on SAPO Services or even for everyone.

The element ESBAccessKey must appear on the message SOAP Header after the complex type ESBCredentials

Example:

ESBCredentials

ESBCredentials is a complex type that is used to pass the credentials in order to authenticate a SOAP request.

Request with username and password
Elements Description
ESBUsername The e-mail of the account that is used to access the API
ESBPassword The password that in combination with the ESBUsername is used to access the corresponding account

Example:

Request with ESBToken

Using a token instead of your username and password can be useful if you don't want to give your credentials to whom is using the API.

In order to generate a ESB Token you must use SAPO Security Token Service (STS). The ESBtoken is valid for 12 hours.

Requesting with an ESBtoken
Go to top