MEP APIs

Inject a Message

This operation enables you to send messages into MEP as if they were sent from an end user.

When you inject a message into MEP, you can set variables related to both the session and the end user. This enables you to create or update custom variables with each injected message. For information, see Including variables in the request.

Note: The Invoke Service operation supports the same basic functionality as the Inject Message operation. The primary differences between the two are that Invoke Service provides enhanced security and high availability capabilities. If you are an existing customer using the Inject Message operation, contact your OpenMarket account manager to determine the migration effort. If you are a new customer, you may want to contact your account manager to determine which operation best fits your needs.

Quick facts

Method	GET
Returns	Accepted response: XML Rejected response: plain text
Available	All regions
Prerequisites	You must have MEP provisioned with OpenMarket, an inject routing code provisioned, and the following roles set in the user account: Main Roles: Routing Manager/User/Viewer Other Roles: HTTP Inject API user Routing - Routing Codes: The inject routing code selected. Users with Routing Manager permission automatically have access to the code.
More information	See MEP Operations and Making Inject Message Requests.

Try It Out

If you'd like to try out this call using cURL, see Making Inject Message Requests, which will take you through how to inject a message.

Making a Request

Definition

GET https://cmx2api.openmarket.com/InjectMessage

The following example is to a UK end user, and specifies that the message uses UTF-8 encoding.

https://cmx2api.openmarket.com/InjectMessage?code=ACME_HTTP_inject&username=MyUsername&password=P4S5W0Rd&from=447700900750&msg=message+text&encoding=UTF-8&network=ORANGEUK

The following request adds information about the user (stored as the custom variable user.name) in the request.

https://cmx2api.openmarket.com/InjectMessage?code=ACME_HTTP_inject&username=MyUsername&password=P4S5W0Rd&from=12515550145&msg=Hello+world&encoding=UTF-8&network=CINGULARUS&user.name=George+Elliot

Query parameters

Parameters must be URL encoded.

Parameter	Description
username	The username used to access MEP. Required: yes Type: string
password	The password associated with the MEP username. Required: yes Type: string
code	The inject routing code that you are sending the message to. The routing code must already exist in your MEP account. Required: yes Type: string
from	The mobile number from which the messages should appear to originate (the end user's number). This must be in international format but without a leading + symbol. For example: 447700900912(UK) or 12515550130(US). Required: yes Type: integer
msg	The text of the message that you are injecting into MEP. You must URL encode the message. Required: yes Type: string
encoding	Identifies the character encoding you are sending the message in. This value tells MEP what character encoding to use to interpret the msg value. Options are: ISO-8859-1 UTF-8 Required: no Default: ISO-8859-1 Type: string
network	The end user's mobile operator. The MEP site hosts a list of mobile operator codes. You will need to log in before you can see the codes. See also Specifying the network parameter. Required: yes Type: string
scope.key	A variable that you wish to set at the same time as the message is processed by MEP. The variable must use the format: scope.key=value You can specify variables with the following scope: request and session user, userservice, and userservicecoll You can only specify custom variables in the request. Built-in variables cannot be altered. The maximum length you can specify for a variable's value is 4096 characters. You can include multiple variables in the same request. For information about variables, see Variables. Required: no

Parameter

Description

username

The username used to access MEP.

Required: yes

Type: string

password

The password associated with the MEP username.

Required: yes

Type: string

code

The inject routing code that you are sending the message to. The routing code must already exist in your MEP account.

Required: yes

Type: string

from

The mobile number from which the messages should appear to originate (the end user's number). This must be in international format but without a leading + symbol. For example: 447700900912(UK) or 12515550130(US).

Required: yes

Type: integer

msg

The text of the message that you are injecting into MEP. You must URL encode the message.

Required: yes

Type: string

encoding

Identifies the character encoding you are sending the message in. This value tells MEP what character encoding to use to interpret the msg value. Options are:

ISO-8859-1
UTF-8

Required: no

Default: ISO-8859-1

Type: string

network

The end user's mobile operator.

The MEP site hosts a list of mobile operator codes. You will need to log in before you can see the codes.

Required: yes

Type: string

scope.key

A variable that you wish to set at the same time as the message is processed by MEP. The variable must use the format:

   scope.key=value

You can specify variables with the following scope:

request and session
user, userservice, and userservicecoll

You can only specify custom variables in the request. Built-in variables cannot be altered. The maximum length you can specify for a variable's value is 4096 characters.

You can include multiple variables in the same request.

For information about variables, see Variables.

Required: no

Header fields

There is no data required in the header.

Response from OpenMarket

Accepted requests

MEP will respond to a successful request with a status code of 200 and return a unique hexadecimal code (e.g.: 2A019B0EB7DB0DF) that identifies the incoming message in the response body.

HTTP/1.1 200 OK
Date: Tue, 15 Mar 2016 16:36:54 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Content-Type: text/plain
			
2A019B0EB7DB0DF

Rejected requests

If your request is rejected then the body of the response will contain a plain text description of the error. For example:

HTTP/1.1 401 Unauthorized
Date: Tue, 15 Mar 2016 11:48:56 GMT
Server: Apache-Coyote/1.1
Connection: close
Transfer-Encoding: chunked
Content-Type: text/plain 

The request was rejected because the routing code is not one of your inject routing codes

See Response error messages below for a list of the possible error messages.

Testing your integration

You can test inject message operations directly with MEP. To test your integration, we suggest the following:

Do not initially assign your routing code to a service. Instead, confirm that your integration is working by making requests. The routing code does not need to be connected to a service to receive requests successfully.

As well as receiving HTTP 200 responses, you can confirm that the inject routing code is receiving the messages in the MEP UI by looking at the Filter Message History for the code. To do this, navigate to the Routing home page, and click on the envelope icon for the code.
Once you are ready, test using your own test services and mobile numbers. If you are messaging in multiple regions, then we recommend using multiple test numbers that are located in your messaging regions.

For more information on using this operation, see Making Inject Message Requests.

Troubleshooting

Response error messages

These error messages are returned in the response body when there was a problem with receiving the request.

Message	Description
Invalid variable name: <variableName>	Additional parameters included in this requests that seem similar to a variable name do not match the format required for a variable name. Check that the parameters (including variables) in the request are spelled correctly and match the format required.
Required parameter 'network' has an invalid value: '<NETWORK>'	The network value you provided does not match a valid mobile operator. Check that it is spelled correctly and matches a valid value. The MEP site hosts a list of mobile operator codes. You will need to log in before you can see the codes.
Required parameter 'from' does not appear to be a valid phone number	Check that the mobile number specified in the from parameter is correct. You must specify these in international format without a leading "+" character, for example: 447700900912.
Required parameter 'msg' is too large (encodes to <number> UTF-8 bytes but maximum is 160)	The value for the msg parameter encodes to over 160 UTF-8 bytes, which exceeds the limits of this API. MEP will reject the request until the value encodes to 160 UTF-8 bytes or less. This means that you will need to reduce the length of your message. Note that, although the most common characters encode to one byte, some characters require two or more bytes, for example "£" and "€"; so although the total number of characters in your message may be less than 160, your message could still consume more than 160 bytes.
The required parameter <parameter> was blank	The specified parameter is mandatory and requires a value. MEP will reject the request until it is sent with a value for the parameter.
The required parameter <parameter> was not provided	The specified parameter is missing, or has been misspelled. Add the parameter and resend.
The request was rejected because no information is held about the http inject code: <CODE>. Please contact a member of the support team	The routing code you specified is not available on the account. Make sure that you are using the routing code supplied for the account by OpenMarket, and that you have entered the code correctly.
The request was rejected because the routing code is not one of your inject routing codes	You have specified one of your normal routing codes rather than one of your inject routing codes.
The request was rejected because the user account has not had inject messaging enabled	Only user accounts with the correct permissions can inject into an inject routing code. You can change the permissions for an account in the MEP UI via Systems > MEP Logins.
The request was rejected because the username or password was incorrect	Either the username or the password parameter has not been correctly specified. Both parameters are mandatory. Check that both parameters are specified, and that you have entered the correct values for each parameter.
Invalid IP Address, you do not have permission to inject SMSs for the routing code	There is an IP address whitelist associated with the account. MEP will only accept inject message requests from IP addresses specified in the whitelist.