Receive SMS

Use our APIs to automatically process incoming SMS messages via SMTP or HTTP.

Incoming SMS and delivery reports

You have two options for processing incoming messages with our API:

Forwarding incoming messages to an email address
Access to an HTTP URL using the HTTP POST method - a separate URL can be configured exclusively for each user

Please note: When using HTTP URL, you must acknowledge receipt of the notification with the response body.

Request body

Element: Notification

Property	Type	Description	Example
messageType	String	"text", "binary", "deliveryReport" – defines the contenttype of your notification	text
notificationId	String	20 digit long identification of your notification. Eg: "050f9005180a2a212469" messageTypes: text, binary, deliveryReport	050f9005180a2a212469
transferId	String	Unique transfer-id to connect the deliveryReport to the initial message. messageTypes: deliveryReport	0051949fe700053c4615
messageFlashSms	Boolean	true \| false – indicates whether you received message is a SMS or a flash-SMS messageTypes: text, binary	true
senderAddress	String	Originator of the sender, eg:4366012345678 messageTypes: text, binary, deliveryReport	4366012345678
senderAddressType	String	international – defines the number format of the mobile originated senderAddress. International numbers always includes the country prefix. messageTypes: text, binary	international
recipientAddress	String	Senders address, can either be international (4366012345678), national (066012345678) or a shortcode (1234) messageTypes: text, binary, deliveryReport	national
recipientAddressType	String	"international"\|"national"\|"shortcode" – defines the number format of the mobile originated message messageTypes: text, binary	international
textMessageContent	String	Text body of the message encoded in UTF-8. In the case of concatenated SMS it will contain the complete content of all segments. messageTypes: text	Hello World!
userDataHeaderPresent	Boolean	true \| false – indicates whether a user-data-header is included within a Base64 encoded byte segment. messageTypes: binary	true
binaryMessageContent	Array of Strings	Content of a binary SMS in an Array of Byte64 Strings (URL safe). messageTypes: binary
deliveryReportMessageStatus	String	"delivered", "undelivered", "expired", "deleted", "accepted", "rejected" messageTypes: deliveryReport	delivered
sentOn	String	ISO 8601 timestamp, eg: "2013-05-27T13:36:00.000+02:00". Point of time sending the message to recipients address. messageTypes: deliveryReport	2013-05-27T13:36:00.000+02:00
deliveredOn	String	ISO 8601 timestamp, eg: "2013-05-27T13:36:00.000+02:00". Point of time of submitting the message to the mobile operators network. messageTypes: deliveryReport	2013-05-27T13:36:00.000+02:00
deliveredAs	String	"sms", "push", "failover-sms", "voice" messageTypes: deliveryReport	sms
clientMessageId	String	In the case of a delivery report, the clientMessageId contains the optional submitted message id. messageTypes: deliveryReport

Response body

You must confirm the notification with statusCode 2000 in your response body. Otherwise, we will retry the delivery of your notification for the duration of the lifetime of your message element.

Attribute	Description
statusCode	status code after processed request
statusMessage	Description of the response status

Example: JSON

Incoming SMS as JSON

{
"messageType": "text",
"notificationId": "02c1d0051949fe70cbfa",
"senderAddress": "4367612345678",
"senderAddressType": "international",
"recipientAddress": "08282709900001",
"recipientAddressType": "national",
"textMessageContent": "Das ist eine Antwort SMS mit Sonderzeichen, Umlauten \u003c\"Ümläuten\"\u003e und €urozeichen."
}

Response body JSON

{
"statusCode" : "...",
"statusMessage" : "...",
}

Example: XML

Incoming SMS as XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<notification>
<messageType>text</messageType>
<notificationId>02c1d0051949fe70cbfa</notificationId>
<senderAddress>4367612345678</senderAddress>
<senderAddressType>international</senderAddressType>
<recipientAddress>08282709900001</recipientAddress>
<recipientAddressType>national</recipientAddressType>
<textMessageContent>Das ist eine Antwort SMS mit Sonderzeichen, Umlauten &lt;&quot;Ümläuten&quot;&gt; und €urozeichen</textMessageContent>
</notification>

Response body XML

<notificationResponse>
<statusMessage>...</statusMessage>
<statusCode>...</statusCode>
</notificationResponse>

Example: PHP

<?php

# 1) get the sms from the received notification
$sms = json_decode(file_get_contents("php://input"));

# 2) do something with $sms
...
...

# 3) respond to the notification
header('Content-Type: application/json; charset=UTF-8');
echo '{"statusCode" : 2000, "statusMessage" : "ok"}';
?>