HTTP API

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:

  • 89.221.166.223
  • 89.221.166.224

And one of the following IP ranges:

  • 46.36.205.80/28
  • 185.221.37.96/28

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>
Parameter Description
request Wraps the entire request
authentication Holder of the API key required to perform Web API calls. Every customer has a unique API key represented by a GUID.
data Wrapper of the entire request data.
message Represents 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
recipients Contains the collection of phone numbers to deliver the message to.
msisdn The phone number for a recipient, including country code (e.g. country code 45 for Denmark).
NOTE: Value cannot exceed 20 characters
messageId
(optional)
This 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
sendername The 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.
text This 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
sendtime The 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.
expireinseconds
(optional)
The 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.
Encoding
(optional)
This is an optional attribute on the text-element. Valid values are: gsm7, utf-8. Default values is gsm7.

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
flash
(optional)
This 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.
statuscallbackurl
(optional)
The 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.
overchargeinfo
(optional)
This element must be included in order to send an overcharged message through the API. If the element is included, all the following attributes must be provided on the element:
  • shortcode: The shortcode used to overcharge, i.e. for overcharging in Denmark the shortcode 1245 is used.
  • countrycode: The countrycode related to the shortcode used. I.e. for 1245 in Denmark, the countrycode must be 45.
  • price: The price in Danish Kroner specified in øre (cents), i.e. 2000 must be specified to overcharge a message with 20 DKK.
  • type: Specified the type of overcharge and can be either 1 (digital products), 2 (donation) or 3 (physical products). In case of questions regarding the type, we are always available by our support phone or email.
  • invoicedescription: The description shown to the end user on the mobile phone bill. (Maximum 30 chars)
respectBlacklist
(optional)
This 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.

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>
Parameter Description
reply Wraps the entire reply for a successful request
recipient Represents 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.

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

Parameter Description
apiKey Your unique API-key
sendername The sender name. (between 3 and 14 characters if only numbers and between 3 and 11 characters if non-numerical characters)
recipients The 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
statuscallbackurl
(optional)
The 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.
flash
(Optional)
true if the message is a flash message, otherwise false. If not specified, default is false.
messageIds
(optional)
Ids 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
expireinseconds
(optional)
The 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.
sendtime
(optional)
The time to send the message. If not specified, the message is sent right away.
respectBlacklist
(optional)
This 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.
text This 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:

Parameter Description
messageid The id of the message
statuscode The message status. Description of each status can be found here: Status code description

Example of a message status call:

http://yourdomain.com/example/messagestatus?messageid=94BE5713-FA88-4AF0-9D9C-1EF332B6EE58&statuscode=2

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

Status codes

A message may have one of the following status codes:

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

Error codes

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

Error: Invalid apiKey

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

Parameter Description
apiKey Your unique API-key
messageIds The 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 can be in the following formats:

M-yyyy

dd-MM-yyyy HH-mm-ss

Examples of requests could look like this:

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

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

Note: When providing only dates, the date ‘08-01-2013’ will be translated into ‘08-01-2013 00:00:00’. This means, that only messages sent the 6th and the 7th January will be included in the result of example A.

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 code Description
-1001 Invalid API code
-1012 Invalid parameter (dates specified are not valid)
-2100 An 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.

Example

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>

Errors

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>

Functionality list

Every call is similar to the example in the previous section. All calls will have a list of parameters and a result xml-element will be returned.

Get all groups

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

Parameter Type Required/optional
apiKey Guid Required

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

Parameter Type Required/optional
apiKey Guid Required
groupId Guid Required

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

Parameter Type Required/optional
apiKey Guid Required
groupName String Required

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

Parameter Type Required/optional
apiKey Guid Required
groupId Guid Required

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

Parameter Type Required/optional
apiKey Guid Required
groupId Guid Required

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

Parameter Type Required/optional Description
apiKey Guid Required
groupId Guid Required
msisdn String Required The 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

Parameter Type Required/optional Description
apiKey Guid Required
groupId Guid Required
msisdn String Required The phonenumber of the recipient including country code, e.g. 4512345678
name String Optional The firstname of the recipient
lastName String Optional The lastname of the recipient
custom1 String Optional
custom2 String Optional
custom3 String Optional
custom4 String Optional
custom5 String Optional
custom6 String Optional
gender int Optional 1 = Female, 2 = Male
birthday Date Optional In the format DD-MM-YYYY
email String Optional
zipCode String Optional

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

Parameter Type Required/optional Description
apiKey Guid Required
groupId Guid Required
msisdn String Required The 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

Parameter Type Required/optional Description
apiKey Guid Required
groupId Guid Required

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

Parameter Type Required/optional Description
apiKey Guid Required
msisdn string Required The phone number including country code, e.g. 4512345678
comment string Optional A 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

Parameter Type Required/optional Description
apiKey Guid Required
msisdn string Required The 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

Parameter Type Required/optional Description
apiKey Guid Required
msisdn string Required The 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

Parameter Type Required/optional Description
apiKey Guid Required

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

Response: All blacklist entries.

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

Example of use

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!';
}

Sending an overcharged message

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

Refunding

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:

  • .NET Framework 3.5+
  • .NET Standard 2.0+
  • .NET Core 2.0+

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: "[HOST-ROOT-URL]",
			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: "[HOST-ROOT-URL]",
			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: "[HOST-ROOT-URL]",
			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: "[HOST-ROOT-URL]",
			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

Below is shown how to define overcharged settings on a message.

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

Below is shown how to define overcharged settings on a message.

// Instantiate the client to use
// NOTE: The api key can be found on top of the documentation page
var smsClient = new FacadeSmsClient(
				hostRootUrl: "[HOST-ROOT-URL]",
				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:

Parameter Value
system_id Individual per account
password Individual per account
hosts smpp-dk1.inmobile.dk
smpp-dk2.inmobile.dk
port 2775 (ssl is required for all connections - no support for non-ssl)
ConnectionMode We 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

  • bind_transmitter
  • bind_receiver
  • bind_transceiver
  • unbind
  • submit_sm
  • deliver_sm
  • enquire_link

DataCodings

Data Coding Hex value Binary encoding
Default 0x0 GSM7
Default Class 0 0x10 GSM7
UCS2 0x8 UTF-16 (big endian byte order)
UCS2 Class 0 0x18 UTF-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

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.