Send a Branded Message

Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.

Indicates whether this is a global one-way or two-way message. You do not need to specify interaction if you are messaging in the US or Canada (the value is ignored). Options are:

• one-way — Uses global one-way messaging
• two-way — Uses global two-way messaging

The values are case-sensitive.

Required: no

Default: See Automated Originator Selection.

Type: string

We provide this ID to you for SMS messaging, and we combine it with the originator (source) you're using. You must include programId for SMS messages sent to US numbers.

Since some branded messages are delivered via SMS as text messages, you will need to include programId in requests for US messages.

Required: no for global messaging, yes for messages sent via short code in the US 

Default: no default

Type: string, 1-50 characters, not case-sensitive

Required for a branded message request. OpenMarket provides you with the value, which is between 1-50 characters.

NOTE: Do not include both campaignId and source object. If you send a request using both campaignId and source, the message will be rejected.

Required: yes

Default: no default

Type: string

Use this when you want to add data, such as individual identifiers (e.g. your own transaction, ticket, or system IDs), which can then be included in reports. It has no effect on the message or its delivery. The value is free-form text 0-200 characters in length.

This value is included in the SMS Detailed report and returned in delivery receipts.

Required: no

Default: no default

Type: string

The phone number to which you are sending an SMS message.

This must be a phone number that includes the country code. Do not include the "+" character. For example:

• 12125550123 (US number)
• 447700900750 (UK number)
• 61491570156 (Australian number)

The length must be between 5 to 20 digits.

Required: yes

Type: string

Identifies what type of message you are sending. For branded messages, specify the type as 'text.'

For text messages, it also identifies whether you are sending the message contents to us as plain text or hex-encoded text.

• text — Message is in UTF-8

The values are case-sensitive.

Required: yes

Type: string

The message sent to the end user's phone. For branded messages the content type must be plain text sent in UTF-8.

Alphanumeric string that is between 1 to 2680 bytes in size.

Required: yes

Type: string

Indicates that you want to receive a delivery receipt for the message. OpenMarket will send the delivery receipt when the mobile operator sends us a final delivery state.

The value is case-sensitive.

Required: yes

Type: string; only valid value is final.

A unique ID that identifies the specific request you made in OpenMarket's systems.

This ID is logged in our systems and is useful if you need to query the request with OpenMarket Support at a later date.

Returned: always

Type: case-insensitive string up to 45 characters in length

Code defining the reason for the outcome of the request. For a list of the codes, see Response error codes below.

Returned: always for rejected requests

Type: string

The authentication details you sent in the requests do not match, or do not exist. Check that your account ID and password are base 64-encoded, and have a colon between them; e.g.:

123-123-123-12345:Secure123

Encodes to:

MTIzLTEyMy0xMjMtMTIzNDU6U2VjdXJlMTIz

We recognized your account, but it is not provisioned for SMS messaging.

Talk to your OpenMarket account manager to provision SMS messaging.

Your OpenMarket account is blocked from sending SMS messages.

Talk to your OpenMarket account manager for more information.

The mobileOperatorId you specified had a non-numeric character.

There is a problem with the value for destination address:

• There is no value specified
• The value is less than 5 characters or greater than 20 characters in length
• The value contains a non-numeric character, like a plus sign, e.g.: "+447700900765"

You must ensure that end user's phone numbers have a country code, and don't include include any additional symbols or letters, e.g.: "447700900765" (UK number) or "12515550145" (US number).

Your request is missing destination address.

You did not include a value for content in your request. The value must be a minimum of 1 byte.

You specified a value for content that is more than the maximum value of 2680 bytes.

This error occurs when the message type is hexEncodedText and we cannot interpret the message content. This may be because the value for charset is incorrect. For example, if you specify Latin-1, then you will get this error if you instead use UTF-16.

You specified a value for mlc that is not one of the valid options. Values are case-sensitive.

You included promotional in your request. The value for this must be either true or false.

You specified a value that is not valid for the source ton. This must be a number, one of: 1,3 or 5.

Occurs when you have included source in your request and:

• You did not include a source address
• You specified a ton of 1 or 3, and your source address is an alphanumeric string (or contains an extra character, such as a "+" sign)
• Your source address is greater than the maximum of 20 characters

You specified a value for type that is not one of the valid options. Values are case-sensitive.

You specified a value for charset that is not one of the valid options. Values are case-sensitive.

You specified that the message is type of wapPush; however, either:

• url is missing from the request
• The value of url is invalid (we do some basic URL validation)
• The length is smaller than 12 characters or greater than 2048 characters

You specified a value for validityPeriod that is more than the maximum value of 259200, or you have included non-digits in the value.

Your request body is either missing, or we cannot parse the XML/JSON in the body.

Your request is missing the message object/element.

You specified a value for note1 that is more than the maximum value of 200 characters.

You specified a value for note2 that is more than the maximum value of 200 characters.

You specified a value for programId that is longer than the 50 characters (the maximum character length).

The value for flash can only be either true or false.

The value for udh can only be either true or false.

Your request included the delivery object/element. When this is included you must also include receiptRequested.

You specified a value for receiptRequested that is not one of the valid options.

Inside the delivery object/element, the value for URL is either: Not a correctly formatted URL—for example example, you must include http:// or https:// in the URL, or gGreater than the maximum of 2048 characters.

You specified a value for interaction that is not one of the valid options.

The end user's number has a country code that is from a region of the world that you are not provisioned to reach. For example, if you exclusively message in the US or CA, you will not be provisioned for messaging end users who reside in other regions.

If you'd like extend your messaging to reach end users globally, please contact your OpenMarket account manager.

Retryable: no

This error is returned when OpenMarket is temporarily unable to finish processing the request. We may have sent the message on to the mobile operator. Therefore we recommend not retrying your request if you receive this error more than once, and contact OpenMarket Support if you continue to receive this error.