NAV
Examples

Introduction

If you are a PHP or .NET developer, you can skip all the documentation and go directly to the PHP and .Net examples

This document is a technical description of The Web API used for external systems to send sms messages and to retrieve a status for each sms message sent.

Our sms gateway is a reliable and scalable gateway for advanced sms services which handles the communication between the client and the operators through a structured and streamlined client API.

The Web API is based on the HTTP protocol and the POST method using XML data structures, hence a general understanding of these concepts is expected of the reader of this document. Each Web API call consists of a single request and a corresponding reply. A request element consists of an authentication element and a data element.

Status callbacks / Incoming SMS-message

You can expect callbacks from one of the following IP addresses:

And one of the following IP ranges:

Sending messages using POST

This method is the recommended method for sending messages and allows the user to send up to 1.000 messages in a single http call.

The Web API provides functionality to send sms messages to mobile phone numbers. This is done using an HTTP POST method towards this address https://mm.inmobile.dk/Api/V2/SendMessages

The request

The request for the ‘SendMessages’ call is sent to the address above using the POST method. The content of the POST should be a single POST variable named ‘xml’ containing a structure like the following:

Simple example:

xml=<request>
	<authentication apikey="12EBA866-9D68-4408-BF1E-BC9E8B63AE5B" />
	<data>
		<message>
			<sendername>FancyShop</sendername>
			<text><![CDATA[Text here]]></text>
			<recipients>
				<msisdn>4588888888</msisdn>
			</recipients>
		</message>

		<!-- statuscallbackurl should only be included
		if using the PUSH message status version -->
		<statuscallbackurl>http://mysite.com/example/messagestatus</statuscallbackurl>
	</data>
</request>

Advanced example with message ids, multiple recipients and other parameters:

xml=<request>
	<authentication apikey="12EBA866-9D68-4408-BF1E-BC9E8B63AE5B" />
	<data>
		<message>

			<sendername>FancyShop</sendername>
			<text encoding="gsm7" flash="false"><![CDATA[Text here]]></text>
			<recipients>
				<msisdn id="Message1">4511223344</msisdn>
				<msisdn id="Message2">4544332211</msisdn>
			</recipients>

			<!-- Specify only if send time should not be immediately -->
			<sendtime>2020-01-20 20:30:00</sendtime>

            <!-- Specify only if you want the message to expire -->
			<expireinseconds>60</expireinseconds>

            <respectblacklist>false</respectblacklist>
		</message>

		<!-- statuscallbackurl should only be included
		if using the PUSH message status version -->
		<statuscallbackurl>http://mysite.com/example/messagestatus</statuscallbackurl>
	</data>
</request>

Overcharged example:

xml=<request>
	<authentication apikey="12EBA866-9D68-4408-BF1E-BC9E8B63AE5B" />
	<data>
		<message>
			<sendername>1245</sendername>
			<text><![CDATA[Thank you for your purchase of DKK 75,00.]]></text>
			<recipients>
				<msisdn>4588888888</msisdn>
			</recipients>

			<!-- 7500 is specified in danish øre equals DK 75,00 -->
			<overchargeinfo countrycode="45"
							shortcode="1245"
							price="7500"
							type="1"
							invoicedescription="" />
		</message>

		<!-- statuscallbackurl should only be included
		if using the PUSH message status version -->
		<statuscallbackurl>http://mysite.com/example/messagestatus</statuscallbackurl>
	</data>
</request>

Refunding an overcharged message:

xml=<request>
	<authentication apikey="12EBA866-9D68-4408-BF1E-BC9E8B63AE5B" />
	<data>

		<!-- messageId: The id of the new message (optional) -->
		<!-- messageIdToRefund: The id of the existing, overcharged message to refund -->
		<refundmessage messageId="MessageId1" messageIdToRefund="MessageId2">
			<text><![CDATA[Your previous purchase has been refunded.]]></text>
		</refundmessage>

		<!-- statuscallbackurl should only be included
		if using the PUSH message status version -->
		<statuscallbackurl>http://mysite.com/example/messagestatus</statuscallbackurl>
	</data>
</request>

Parameters

ParameterRequired?Description
requesttrueWraps the entire request
authenticationtrueHolder of the API key required to perform Web API calls. Every customer has a unique API key represented by a GUID.
datatrueWrapper of the entire request data.
messagetrueRepresents a message with a specific text and sender name to be sent to one or more recipients. A request may consist of multiple messages with different text and/or senders.
recipientstrueContains the collection of phone numbers to deliver the message to.
msisdntrueThe phone number for a recipient, including country code (e.g. country code 45 for Denmark).
NOTE: Value cannot exceed 20 characters
messageIdfalseThis is an optional attribute on the individual msisdn element. This is used as the unique reference for the message to the particular msisdn. If not provided, a guid is generated for the message and returned in the response.
NOTE: Value cannot exceed 50 characters
sendernametrueThe name of the sender displayed to the receiver of the message. The maximum length of the sender is 11 chars and only a-z, A-Z and 0-9 are valid characters.
texttrueThis is the actual text message to be sent to the recipients. The content of the element should be wrapped in a element.
NOTE: Value cannot exceed 10.000 characters
sendtimefalseThe time for the message to be sent. The time must be specified in CET time in the format yyyy-MM-dd HH:mm:ss e.g. <sendtime>2015-03-21 17:05:00</sendtime> Leave out element entirely or leave blank to send the message immediately.
expireinsecondsfalseThe amount of seconds the message is valid for. If the message is not sent, before the seconds has passed, it will not be sent at all. Leave out element entirely or leave blank if you don’t want the message to expire.
encodingfalseThis is an optional attribute on the text-element. Valid values are: gsm7, utf-8. Default values is gsm7. Read more about encodings here: Charsets
flashfalseThis is an optional attribute on the text-element. If set to true, the sms message will be shown on the display immediately when the user receives the message. The value defaults to “false” when not specified, indicating the message to be a standard sms message.
statuscallbackurlfalseThe HTTP GET url to be called when a message status changes. Details about the message status callback can be found in the section Message statuses (PUSH). This should only be included if using the PUSH version of getting message statuses.
overchargeinfofalseThis element must be included in order to send an overcharged message through the API. See the parameters here: Overcharged parameters
respectblacklistfalseThe value defaults to “true” when not specificed, indicating the message will respect blacklisting and not send to phone numbers in the blacklist.

Overcharged parameters

GSM7 charset

This is the standard charset and contains of the following characters:

@ £ $ ¥ è é ù ì ò Ç Ø ø Å å ? _ F G O S T Æ æ ß É ! " # ¤ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ¡ A B C D E H I J K L M N P Q R U V W X Y Z Ä Ö Ñ Ü § ¿ a b c d e f g h i j k l m n o p q r s t u v w x y z ä ö ñ ü à

When using gsm7 the total sms count in a message is calculated using the following method:

1 - 160 characters = 1 SMS
161 - 306 characters = 2 SMS’s
307 - 459 characters = 3 SMS’s
460 - 612 characters = 4 SMS’s

UTF-8 charset

This is the enhanced charset and includes special characters.

When using utf-8 the total sms count in a message is calculated using the following method:

1 - 70 characters = 1 SMS
71 -134 characters = 2 SMS’s
135 - 201 characters = 3 SMS’s
202 - 268 characters = 4 SMS’s

The reply

After sending a successful request, a reply of the following format is returned:

<reply>
	<recipient msisdn="4511223344" id="Message1" />
	<recipient msisdn="4544332211" id="Message2" />
	<recipient msisdn="4588888888" id="13cab0f4-0e4f-44cf-8f84-a9eb435f36a4" />
</reply>
ParameterDescription
replyWraps the entire reply for a successful request.
recipientRepresents a single recipient in the request. The msisdn-attribute matches the request msisdn and the id-attribute contains the id of the recipient for the specific message in the system. Any further reference to recipient (e.g. in the ‘GetStatusMessage’ call) will be based on this id.

Note: The recipients are listed in a single, flat list as opposed to the group arrangement in the request

Error codes

In case of errors when receiving a request, the Web API will return a single error code represented by a number. The list of possible error codes in the ‘SendMessages’ call are listed here:

Error codeDescription
-1001The provided api key is either missing or not valid.
-1002The provided content of the POST variable “xml” is not valid XML.
-1003The XML structure does not reflect the required structure.
-1004A sender name is missing.
-1007No text message provided.
-1008Message text exceed the limit of 10.000 chars.
-1009One or more messages have no recipients.
-1010No authentication element provided.
-1011The same message id has been used for multiple messages.
-1012Invalid parameter. E.g. start and end dates are in wrong format.
-1013Invalid encoding specified.
-1015Invalid flash value. Valid values are “true” and “false”.
-1016Overcharge country code missing or invalid.
-1017Overcharge shortcode missing or invalid.
-1018Overcharge price missing or invalid.
-1019Overcharge type missing or invalid.
-1020The message status callback url is not valid.
-1021Invalid send time.
-1022Overcharge invoice description length exceeded
-1023Invalid “expireinseconds” value. Valid values are whole positive numbers, for example “60”.
-1024Invalid ‘respect blacklist’ value.
-1041Message Id is too long. Maximum length is 50 chars.
-2100error occurred, different from the above described cases.
-2101Access denied.

Sending messages using GET

This method is designed for sending single messages or for use for interaction from systems where POST and/or XML is not an option. For sending bulk messages we recommend sending using the POST method instead if possible.

The request

Examples of URLs to send a messageThe URL to call when sending a single message has the following format:

Simple example:

https://mm.inmobile.dk/Api/V2/Get/SendMessages?apiKey=YOUR_KEY&sendername=SENDERNAME&text=Hello world&recipients=MSISDN_1

Advanced example:

https://mm.inmobile.dk/Api/V2/Get/SendMessages?apiKey=YOUR_KEY&sendername=SENDERNAME&text=Hello world&flash=false&recipients=MSISDN_1,MSISDN_2&sendtime=2020-01-20 20:30:00&messageIds=1,2
ParameterRequired?Description
apiKeytrueYour unique API-key
sendernametrueThe sender name. (between 3 and 14 characters if only numbers and between 3 and 11 characters if non-numerical characters)
recipientstrueThe recipients to send to. These are MSISDNs which are the country code and phone number, e.g. 4512345678. In case of multiple receivers of the same message, multiple recipients can be specified.
NOTE: A single msisdn cannot exceed 20 characters.
statuscallbackurlfalseThe Http GET url to be called when a message status changes. Details about the message status callback can be found in the section Message statuses (PUSH). This should only be included if using the PUSH version of getting message statuses.
flashfalsetrue if the message is a flash message, otherwise false. If not specified, default is false.
messageidsfalseIds of for each of the specified recipients message. If not specified, the system will generate ids for the messages.
NOTE: A single message id cannot exceed 50 characters.
expireinsecondsfalseThe amount of seconds the message is valid for. If the message is not sent, before the seconds has passed, it will not be sent at all. Leave out element entirely or leave blank if you don’t want the message to expire.
sendtimefalseThe time to send the message. If not specified, the message is sent right away.
respectblacklistfalseThis is an optional attribute. The value defaults to “true” when not specificed, indicating the message will respect blacklisting and not send to phone numbers in the blacklist.
texttrueThis is the actual text message to be sent to the recipients. The content of the element should be wrapped in a <![CDATA[ … ]]> element.
NOTE: Text value cannot exceed 10.000 characters.

The reply

After sending a successful request, a reply of the following format is returned:

MSISDN:MESSAGEID
MSISDN:MESSAGEID
MSISDN:MESSAGEID

In the example case above, the following data would be returned:

4511223344:Message1
4544332211:130345eb-7906-44af-86de-9d9d73c0f915
4588888888:13cab0f4-0e4f-44cf-8f84-a9eb435f36a4

Error codes

In case of errors during the http call, a message of the following format will be returned:

Error: Invalid apiKey

Important: It is strongly recommended to always check if the returned string starts with Error: and handle the error case accordingly.

Message statuses - PUSH version

Getting message statuses using the PUSH works by you providing a status-url when sending the message and we will then call the url when a message has either been delivered or fails delivery.

The benefits of the PUSH method is that you don’t need a running job checking for message statuses.

When the url is called, the list of GET parameters are added to the url:

ParameterDescription
messageidThe id of the message
statuscodeThe message status. Description of each status can be found here: Status code description
sentdateThe date of sending the message. Format: dd-MM-yyyy HH:mm:ss
donedateThe date of completion of a given message. Format: dd-MM-yyyy HH:mm:ss
smscountThe quantity of SMS’s sent
ischargedIf the message is charged or not. true or false

Example of a message status call (url encoded):

http://yourdomain.com/example/messagestatus?messageid=94BE5713-FA88-4AF0-9D9C-1EF332B6EE58&statuscode=2&sentdate=19-02-2020+13%3a16%3a38&donedate=19-02-2020+13%3a16%3a38&smscount=1&ischarged=true

The response of the call should just be an HTTP status code 200.

Message statuses - PULL version

Getting message statuses with the PULL method means that you will call our API in intervals to get all latest message statuses changed since the last call.

The benefits of the PULL version is, that you do not need to provide a web server to receive calls.

The request

To get all changed message statuses, performing an HTTP GET call towards this address:

https://mm.inmobile.dk/Api/V2/Get/GetMessageStatus?apiKey=INSERT_YOUR_KEY_HERE

The reply

After sending a successful request, all changed message statuses will be returned. Only when message status changes, will the message apear in the result again.

Example: a single message is sent through the API. Calling the GetMessageStatus right after, will not give any result. When the message changes status, a proceeding call to GetMessageStatus will then return the message. After returning the message, this specific message will not be returned in any additional calls, unless the message changes status once again.

The format of the result data is in the format MESSAGE_ID:STATUS_CODE:STATUS_DESCRIPTION.

Description of each status can be found here: Status code description

An example is shown below:

5a43040e-53dd-4bce-ba15-dd776d519ec7:2:Delivered
f6b97bf9-7062-4eac-864c-e384523831b5:2:Delivered
24ed1b39-527b-4c76-a5af-2fad93ad5a9c:2:Delivered
5ebd853f-9bf5-477b-8068-546e8344e7c8:2:Delivered
019382ad-a0f4-4d07-99a9-b539a7d98596:-6:NotDeliveredRemovedFromGateway

Error codes

In case some error occurs when retrieving message statuses, the returned result will instead be as the following example:

Error: Invalid apiKey

Status codes

A message may have one of the following status codes:

General status codes

Status CodeDescription
3SentButNoReports
2Delivered
1AwaitingOperator
0New
-1UndeliverableMessage
-2MsisdnBlacklistedByOperator
-3InvalidMobileNumber
-4CountryNotAvailable
-5DeliveryTimeout
-6NotDeliveredRemovedFromGateway
-8InsufficientFunds
-9AuthorizeFailed
-10CaptureFailed
-11OverchargeDonationLimitExceeded
-12OverchargeTypeNotActivated
-13OverchargeSettingsNotValid
-14SenderNameBlocked
-15RouteNotAvailable
-16RefundNotAvailable
-17RefundNotPossibleForMessage
-18RefundFailed
-19RefundNotPossibleForPendingMessage
-20RefundNotPossibleForFailedMessage
-21RefundFailedAlreadyRefunded
-80ImportedFromOtherSystem
-99SubmitFailed
-100CommunicationError
-101UnknownId
-102Cancelled
-103UnknownErrorProcessingMessage
-104UnknownIdAtOperator
-105MsisdnBlacklistedOnAccount
-201SuspiciousSmsContent
-202AccountDeactivated

SMPP specific codes

Status CodeDescription
-300PduSequenceIncomplete
-301PduSequenceInvalid

Cancel messages

The request

If a scheduled message has not yet been sent, it can be cancelled using the API. The following url:

https://mm.inmobile.dk/Api/V2/Get/CancelMessages?apiKey=YOUR_KEY&messageIds=MSG_ID
ParameterDescription
apiKeyYour unique API-key
messageIdsThe id of the message to cancel. For cancelling multiple messages in a single call, seperate message ids with a comma, e.g. messageIds=111,112

The reply

When cancelling messages the reply is always concidered successfull if the parameters are valid, no matter if 0, more or all messages are cancelled. The reply is in the following format:

success: 1 cancelled.

Error codes

In case some error occurs when retrieving message statuses, the returned result will instead be as the following example:

Error: Invalid apiKey

Incoming messages

It is possible to make the Web-API call an external URL when a certain message is received. Say a person texts “COMPANYNAME Hello” to 1245 from her cell phone. A URL can then be configured to be called in the format https://mywebsite.com/path?sender=4512345678&message=COMPANYNAME%20Hello

The URL above is just an example. It is possible to configure exactly how the URL looks like using the online web administration.

Statistics summary

The Web API provides statistics on the messages handled in the system. The reply contains details on the message distribution by status. A total message count and a total sms count is also provided. In the following, ‘message’ and ‘sms’ will mean different things. A message covers the entire message for the user to receive as a whole on a phone. A message consists of 1 to 4 sms’s.

The request

Querying the summary statistics is done using the HTTP GET method towards the address: https://mm.inmobile.dk/Api/V2/Statistics/Summary with an api key, a start date and and end date. The api key is the customer api key used for all API calls. The two dates

The dates are specified in the following format:

dd-MM-yyyy

Example:

https://mm.inmobile.dk/Api/V2/Statistics/Summary?apikey=f3e25d84-367d-40cb-bcbb-ee87c05a&from=06-01-2013&to=08-01-2013

Note: The start and end date are both included. so providing the value 08-01-2013 as end date, means that all message during this day are also included.

The reply

When querying the summary statistics, a reply of the following format will be returned:

<reply>
	<summary from="06-01-2013 00:00:00" to="08-01-2013 00:00:00">
		<messages messagecount="12" smscount="18">
			<status code="2" messagecount="8" smscount="10" />
			<status code="1" messagecount="3" smscount="6" />
			<status code="0" messagecount="1" smscount="2" />
		</messages>
	</summary>
</reply>

The messages element contains the total number of messages and the total number of sms’s sent within the given time frame. The status elements contains the distribution of messages on status codes.

Error codes

When querying the summary statistics API, the following error codes may be returned instead of the reply xml:

Error CodeDescription
-1001Invalid API code
-1012Invalid parameter (dates specified are not valid)
-2100An error occurred different from the above described cases

Groups and Recipients

Administration of groups and recipients is available through a Web-API consisting of GET calls. Every call will consist of a URL containing a list of parameters and the result will always be an xml document by the name ApiResult. This result element will contain a data-element with the result or in case an error occurred, an exception-element will exist instead.

Say a customer has the ApiKey ‘abcdef’, getting all groups is done calling the following address: https://mm.inmobile.dk/Api/V3/Groups/GetAll?apiKey=abcdef

This will then result in a complete list of groups will then be returned in the following format:

<apiresult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Data>
		<Group>
			<Id>b684abbf-548f-4808-acfd-06cab85cd89c</Id>
			<Name>CustomerGroup</Name>
		</Group>
		<Group>
			<Id>2edd78ca-b50b-4c92-827d-09836fb782a8</Id>
			<Name>EmployerGroup</Name>
		</Group>
	</Data>
</apiresult>

Say the customer used an invalid ApiKey causing the call to fail, the result will contain an “Exception”-element instead of a “Data”-element with details of the error as shown below:

<apiresult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Exception>
		<Type>InvalidApiKeyException</Type>
		<Message>
			[Error details]
		</Message>
	</Exception>
</apiresult>

Get all groups

URL: https://mm.inmobile.dk/Api/V3/Groups/GetAll

ParameterTypeRequired?Description
apiKeyGuidtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Groups/GetAll?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228

Response: A complete list of groups for the customer.

Get specific group

URL: https://mm.inmobile.dk/Api/V3/Groups/GetSingle

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Groups/GetSingle?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=3B8B2365-3445-4684-BF7B-A46781F78E93

Response: The specific group.

Create group

URL: https://mm.inmobile.dk/Api/V3/Groups/Create

ParameterTypeRequired?Description
apiKeyGuidtrue
groupNameStringtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Groups/Create?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupName=Vip%20club

Response: The created group.

Delete group

URL: https://mm.inmobile.dk/Api/V3/Groups/Delete

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Groups/Delete?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=892122E7-7944-40C5-832C-183BCEC8367E

Response: The deleted group.

Get all recipients in a group

URL: https://mm.inmobile.dk/Api/V3/Recipients/GetAll

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Recipients/GetAll?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=892122E7-7944-40C5-832C-183BCEC8367E

Response: A complete list of recipients in the specific group.

Get single recipients in a group

URL: https://mm.inmobile.dk/Api/V3/Recipients/GetSingle

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue
msisdnStringtrueThe phonenumber of the recipient including country code, e.g. 4512345678

Example URL:

https://mm.inmobile.dk/Api/V3/Recipients/GetSingle?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=892122E7-7944-40C5-832C-183BCEC8367E&msisdn=4512345678

Response: The requested recipient.

Create or update recipient

This call is used for both creating and updating a recipient. In case a recipient already exists, this is updated with all provided parameters. In other cases, a new recipient is created.

URL: https://mm.inmobile.dk/Api/V3/Recipients/CreateOrUpdate

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue
msisdnStringtrueThe phonenumber of the recipient including country code, e.g. 4512345678
nameStringfalseThe firstname of the recipient
lastNameStringfalseThe lastname of the recipient
custom1Stringfalse
custom2Stringfalse
custom3Stringfalse
custom4Stringfalse
custom5Stringfalse
custom6Stringfalse
genderIntfalse1 = Female, 2 = Male
birthdayDatefalseIn the format DD-MM-YYYY
emailStringfalse
zipCodeStringfalse

Example URL:

https://mm.inmobile.dk/Api/V3/recipients/CreateOrUpdate?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=ecbda0a4-80ce-4569-9ac3-eac274607c0f&msisdn=4512345678

Response: The recipient (either updated or created).

Delete single recipient

URL: https://mm.inmobile.dk/Api/V3/Recipients/Delete

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue
msisdnStringtrueThe phonenumber of the recipient including country code, e.g. 4512345678

Example URL:

https://mm.inmobile.dk/Api/V3/Recipients/Delete?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=892122E7-7944-40C5-832C-183BCEC8367E&msisdn=4512345678

Response: The deleted recipient.

Delete all recipients in group

URL: https://mm.inmobile.dk/Api/V3/Recipients/DeleteAll

ParameterTypeRequired?Description
apiKeyGuidtrue
groupIdGuidtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Recipients/DeleteAll?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&groupId=892122E7-7944-40C5-832C-183BCEC8367E

Response: The affected count.

Add number to blacklist

URL: https://mm.inmobile.dk/Api/V3/Blacklist/Create

ParameterTypeRequired?Description
apiKeyGuidtrue
msisdnStringtrueThe phone number including country code, e.g. 4512345678
commentStringfalseA comment to be set in the blacklisting, max length: 1000 characters

Example URL:

https://mm.inmobile.dk/Api/V3/Blacklist/Create?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&msisdn=4512345678&comment=User requested by phone

Response: The created entry in the blacklist.

Remove from blacklist

URL: https://mm.inmobile.dk/Api/V3/Blacklist/Delete

ParameterTypeRequired?Description
apiKeyGuidtrue
msisdnStringtrueThe phone number including country code, e.g. 4512345678

Example URL:

https://mm.inmobile.dk/Api/V3/Blacklist/Delete?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&msisdn=4512345678

Response: The deleted entry.

Get number info in blacklist

URL: https://mm.inmobile.dk/Api/V3/Blacklist/GetSingle

ParameterTypeRequired?Description
apiKeyGuidtrue
msisdnStringtrueThe phone number including country code, e.g. 4512345678

Example URL:

https://mm.inmobile.dk/Api/V3/Blacklist/GetSingle?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228&msisdn=4512345678

Response: The blacklist entry matching the specified msisdn.

Get all entries in blacklist

URL: https://mm.inmobile.dk/Api/V3/Blacklist/GetAll

ParameterTypeRequired?Description
apiKeyGuidtrue

Example URL:

https://mm.inmobile.dk/Api/V3/Blacklist/GetAll?apiKey=2A851681-7B78-44A5-8E0A-2EAE13E85228

Response: All blacklist entries.

Email to SMS

You can send an SMS text message via email. To do so, you’ll have to log into the website, go to “Send SMS”, and find the option “E-mail til SMS”. Here you’ll need to whitelist either a domain, or a specific emailaddress. If you’re whitelisting a domain, you’ll need to prepend it the an @ sign. For example: “@inmobile.dk”. Please note, that a domain can only be whitelisted on one account at a time.

After this is done, you can send an email to the following address: “MSISDN@sms.inmobile.dk” where “MSISDN” is the MSISDN of the recipient you want to send to. An MSISDN consists of both a country code, and a phonenumber. For example: if you want to send a message to the danish number 12345678, you would have to send an email to “4512345678@sms.inmobile.dk

Managed URL calls

Status callbacks and requests to a specific URL, based on an incoming message, are both handled by being added to a table, we call “managed-url-calls”. If a request doesn’t return a HTTP statuscode within the 200 series, or a timeout occurs, the request is marked as failed. Failed requests are retried up to 6 times, with increasing intervals between each attempt. If one of the attemps, after a failed attempt, is successful, then the request is marked as such, and is then finished. However, if all the attemps fail (6 attemps, last attempt happens approximately 6 hours after the first), there is an extra feature, which sends an email to all the users on the account, informing them about the failed request. This is to ensure that no failed requests will be overlooked. Furthermore, it is possible to view all requests (failed or otherwise) via our UI, where it’s possible to see the return-code, response times and how many attempts each request took. Requests are saved for 30 days, after which, all history regarding a request is deleted. By default, only one domain will get a request at a time on an account, no matter how many are queued. This is to ensure that the receiving server is not overloaded by requests. If needed, we can change this behaviour on a specific account, if you merely contact us.

Code snippets

PHP library

Contains a PHP-class along with examples of use, currently supporting sending messages and getting message statuses.

Download our PHP API client from GitHub

This is a demonstration of sending a standard text message to a cell phone.

<?
require_once 'mm_apiclient.class.php';

$apiKey = 'INSERT APIKEY';// Found at the top of the documentation page

// Instantiate an API client object
$MM_Connector = new MM_Connector(
        $apiKey,
        'https://mm.inmobile.dk', // Server root address
        'http://mywebsite.com/example/messagestatus' // Optional for status callbacks
        );

/*
Prepare some messages to be sent. You can repeat this step multiple times
to send multiple messages in a single http call
*/
$msg = new MM_Message(
        'Hello world', // Message text
        array('4512345678'), // Msisdn (phonenumber with countrycode) for the receiver
        '1245'); // The sendername. This could be a phonenumber or your company name

// Optionally a send time can be specified
// $msg->setSendTime('2020-01-20 18:30:00');

// Optionally flash can be specified
// $msg->setFlash(true);

// Optionally an expire time in seconds can be specified
// $msg->setExpireInSeconds(60);

// Optionally respect blacklist can be specified
// $msg->setRespectBlacklist(false);

$MM_Connector->addMessage($msg);

/* Send the payload */
$success = $MM_Connector->send();
if($success)
{
    /* Read the message ids */
    $messageIds = $MM_Connector->getMessageIds();

    /*
    $messageIds contains an array with message id's and its corresponding msisdn

    Example:
    Array
    (
        [0] => Array
            (
                [msisdn] => 4512345678
                [id] => fd0ab916-e960-49d0-bb2e-361771818393
            )
    )
    */

    print_r($messageIds);
    echo 'Success!';
}
else
{
    /*
    This function returns the remote error code
    */
    print_r($MM_Connector->getError());
    echo 'Error!';
}
?>

Below is an examle of how to send an overcharged message. Type ‘MM_Premium_Message’ should be used instead of MM_Message - everything else works the same way.

<?
/*
To send an overcharged message use the following function
*/
$MM_Connector->addMessage(new MM_Premium_Message(
    'Thankyou for your purchase!', // Text messages
    array('4512345678'), // The receiver
    '1245', // The sendername (Always a shortcode when overcharged message
    '150', // The amount in cents, e.g. 150 for 1,50 DKK
    '1', // The type, Possible types: 1 = Digital products, 2 = Donation, 3 = Physical products
    '45', // The country code
    '1245', // The shortcode
	'' // Description to show in the users invoice (maximum 30 characters)
));
?>

Below is an examle of how to send an overcharged message using the type ‘MM_Refund_Message’.

<?
/*
To refund a message, use the following function
*/
$MM_Connector->addRefund(new MM_Refund_Message(
    'The 1,50 DKK has been refunded.!', // The text sent to the mobile user
    'bed390df-0ff9-44c0-8541-b3a6cfbc7c84' // The id from the message to refund
));
?>

C# library

This is a project made in csharp, currently supporting sending messages and getting message statuses.

Supported targets are:

Download latest client from NuGet

or

View the source code on GitHub

Example of use: Send messages

// Instantiate the client to use
// NOTE: The api key can be found on top of the documentation page
var smsClient = new FacadeSmsClient(
			hostRootUrl: "https://mm.inmobile.dk",
			apiKey: "INSERT APIKEY");

// Create a list of messages to be sent
var messagesToSend = new List<ISmsMessage>();
var message = new SmsMessage(
			msisdn: "4512345678", // The mobile number including country code
			text: "This is the text to be sent.",
			senderName: "SendersName", // i.e. 1245 or FancyShop
			encoding: SmsEncoding.Gsm7);
messagesToSend.Add(message);

// Send the messages and evaluate the response
try
{
	var response = smsClient.SendMessages(
		messages: messagesToSend,
		messageStatusCallbackUrl: "http://mywebsite.com/example/messagestatus");
}
catch (SendMessageException smex)
{
	// Catch exception to see error
	Console.WriteLine(smex.Message);
}

Example of use: Send messages and ignore blacklistings

// Instantiate the client to use
// NOTE: The api key can be found on top of the documentation page
var smsClient = new FacadeSmsClient(
			hostRootUrl: "https://mm.inmobile.dk",
			apiKey: "INSERT APIKEY");

// Create a list of messages to be sent
var messagesToSend = new List<ISmsMessage>();
var message = new SmsMessage(
			msisdn: "4512345678", // The mobile number including country code
			text: "This is the text to be sent.",
			senderName: "SendersName", // i.e. 1245 or FancyShop
			encoding: SmsEncoding.Gsm7,
            respectBlacklist: false); // Also send to blacklisted phone numbers
messagesToSend.Add(message);

// Send the messages and evaluate the response
try
{
	var response = smsClient.SendMessages(
		messages: messagesToSend,
		messageStatusCallbackUrl: "http://mywebsite.com/example/messagestatus");
}
catch (SendMessageException smex)
{
	// Catch exception to see error
	Console.WriteLine(smex.Message);
}

Example of use: Send messages with own message ID

var message = new SmsMessage(
	msisdn: "4512345678", // The mobile number including country code
	text: "This is the text to be sent.",
	senderName: "SendersName", // i.e. 1245 or FancyShop
	encoding: SmsEncoding.Gsm7,
	messageId: "[MY-MESSAGE-ID]"); // Identifier of the message (duplicate ids not allowed)

Example of use: Request messages statuses (PULL)

// Instantiate the client to use
// NOTE: The api key can be found on top of the documentation page
var smsClient = new FacadeSmsClient(
			hostRootUrl: "https://mm.inmobile.dk",
			apiKey: "INSERT APIKEY"); // Can be found on top of the documentation page

// Get all changed message statuses since last call
// The reponse contains messageids paired with they respective message status
var response = smsClient.GetMessageStatus();

Example of use: Cancelling a scheduled message

// Instantiate the client to use
// NOTE: The api key can be found on top of the documentation page
var smsClient = new FacadeSmsClient(
			hostRootUrl: "https://mm.inmobile.dk",
			apiKey: "INSERT APIKEY"); // Can be found on top of the documentation page

// Cancel the messages with id 'MessageId1' and 'MessageId2'
// The reponse contains an object with the cancelled count
// To validate the number of cancelled messages, read response.CancelCount
var response = smsClient.CancelMessage(new List<string>(){ "MessageId1", "MessageId2" });

Example of use: Send overcharged messages:

var message = new SmsMessage(); // Remember to fill constructor
message.OverchargeInfo = new OverchargeInfo(
	overchargePrice: 150, // Price in cents, e.g. 150 for 1,50 DKK
	shortCodeCountryCode: "45",
	shortCodeNumber: "1245",
	overchargeType: OverchargeType.Service,
	invoiceDescription: "");

Example of use: Refund an overcharged messages:

// Instantiate the client to use
// NOTE: The api key can be found on top of the documentation page
var smsClient = new FacadeSmsClient(
				hostRootUrl: "https://mm.inmobile.dk",
				apiKey: "INSERT APIKEY");

// Create a list of messages to be sent
var messagesToSend = new List<ISmsMessage>();

// Add a refund message that points to an existing overcharged message
var message = new RefundMessage(messageIdToRefund: "MessageId123",
messageText: "We have refunded the 100 DKK previously charged from your phone bill");
messagesToSend.Add(message);

// Send the messages and evaluate the response
try
{
	var response = smsClient.SendMessages(
		messages: messagesToSend,
		messageStatusCallbackUrl: "http://mywebsite.com/example/messagestatus");
}
catch (SendMessageException smex)
{
	// Catch exception to see error
	Console.WriteLine(smex.Message);
}

SMPP

We offer support for SMPP version 3.4 which is the industry standard protocol for sms communication. Our setup provides redundant connection options with an endpoint pointing at two different locations.

Connecting

In order to connect you need the following:

ParameterValue
system_idIndividual per account
passwordIndividual per account
hostssmpp-dk1.inmobile.dk
smpp-dk2.inmobile.dk
port2775 (ssl is required for all connections - no support for non-ssl)
ConnectionModeWe support all 3 modes: Transceiver, Transmitter and Receiver.
Only Transceiver and Receiver modes can receive delivery reports.
Only Transceiver and Transmitter mode is allowed to send submitSm messages.

In order to get an smpp system id, contact inMobile.

Encryption over ssl/tls

As states previously, all communication must happen on encrypted connections. This requires for the applications to download and use the certificate used at https://mm.inmobile.dk (The certificate is a wildcard certificate for *.inmobile.dk)

Supported message types

DataCodings

Data CodingHex valueBinary encoding
Default0x0GSM7
Default Class 00x10GSM7
UCS20x8UTF-16 (big endian byte order)
UCS2 Class 00x18UTF-16 (big endian byte order)

Data codings are mapped to binary encodings according to the table above, e.g. when using data coding UCS2 the binary data must be UTF-16 encoded. In some languages, e.g. C#, this is known as “Big endian unicode”. UCS2 is a subset of UTF-16, so using UCS2 specifically on the client side will also work just fine.

Delivery reports

Example of our delivery report formats

id:b1e50673-f8b8-41e8-a143-07a43bb8c86b sub:001 dlvrd:001 submit date:1911121314 done date:1911121314 stat:DELIVRD err:005

The error code in this example (005) is the absolute value of the message status code -5 defined in the Status code description

Incoming messages

To get deliver_sm or incoming messages via SMPP, you’ll have to log in to the UI, and have PDU’s forwarded to your system_id.
Contact support for further help, with setting this up.

Limitations

The source_addr parameter has a max length of 15 characters. If the source_addr parameter is any longer, anything after the 15th character, will be discarded.

Maintenance

SMPP is an async protocol meaning that multiple requests and replies may be transported over the wire at a given time. In order to avoid losing any data in case of maintenance or updating our smpp server, we have taken measures ensuring controlled shutdown and restart.

In the event of an smpp server system restart, any newly sent submitSm-message will be rejected with the reply ESME_RSUBMITFAIL and clients will be sent an unbind message. Right after, the connection will be disconnected. In case a client tries to rebind at the exact time, that a server is about to restart, the bind attempt will be replied with a generic ESME_RBINDFAIL reply.

A typical restart of an smpp server takes 2 seconds and all planned restarts and maintenance will be informed in advanced to the users of all accounts using our smpp connection.