Falls du es noch nicht getan hast, werfe bitte zuerst einen Blick auf die Ersten Schritte bevor du dich hier zu sehr vertiefts. Danke!

SMS Senden API

Funktion: sendSms

Versendet GSM und Unicode SMS Text Nachrichten. Fasst lange Nachrichten automatisch zu langen SMS (mit bis zu 765 Zeichen) zusammen.

Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

number	Die Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789	string

message	The SMS Inhalt. My-Cool-SMS erkennt automatisch ob es sich um eine Unicode oder GSM Nachricht handelt und versendet die SMS im jeweiligen Format. Der Uniocde Parameter kann benutzt werden um eine bestimmte Kodierung zu erzwingen. Falls Unicode auf true gesetzt wird muss der SMS Inhalt in UCS2 Notation übergeben werden. Wenn Unicode auf false gesetzt ist, wird die Nachricht im GSM Standard versendet und darf nur Zeichen aus dem GSM7 Alphabet enthalten. Lange Nachrichten werden automatisch konkateniert (bis zu fünf Nachrichten oder 765 Zeichen für GSM bzw. 335 Zeichen für Unicode SMS). Bitte beachte dass der Unicode Paramater bei Aufrufen mit der GET Methode immer verwendet werden sollte, da es in diesem Fall nicht möglich ist automatisch zwischen Unicode und GSM zu unterscheiden.	string

Hinweis: Erfahre mehr über GSM, Unicode und UCS2.

Optionale Parameter

Parameter	Beschreibung	Typ

unicode	Erzwingt eine Unicode oder GSM Kodierung der SMS. Falls true verwendet wird muss der SMS Inhalt mit UCS2 Notation übergeben werden. Falls auf false gesetzt darf der SMS Inhalt lediglichen Zeichen aus dem GSM7 Alphabet enthalten. Ist auf NULL voreingestellt und erkennt in diesem Fall die zu verwendende Kodierung automatisch.	boolean

senderid	Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789 Alternativ darf eine alphanumerische Zeichenkette mit bis zu 11 Zeichen verwendet werden, z.B. "Firmenname"	string

scheduletime	Versendet die Nachricht zu einem bestimmten Zeitpunkt. Erfordert einen Timestamp im ATOM Format (mit Zeitzone), zum Beispiel: "2011-04-17T17:59:36.67+08" oder "2011-04-17 17:59:36-02"	timestamp with timezone

callbackurl	Rückruf URL für Status-Updates und Sendeberichte für diese Nachricht. Zum Beispiel: http://www.mein-server.de/callback.php	string

Hinweis: Erfahre mehr über Sendebericht Rückrufe.

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "callbackurl":"http://www.my-server.com/callback.php"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

smsid	Unique ID für diese SMS. Sollte auf Client-Seite als Referenz ID für Sendeberichte gespeichert werden.	string(32)

body	Der SMS-Inhalt als Unicode Text-String	string

bodyucs2	Der SMS-Inhalt in UCS2 Bytecode-Notation	string

bodygsm7	Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde)	string \|\| NULL

senderid	Zeigt an ob die Ziel-Rufnummer dynamische Senderkennungen unterstützt	boolean

unicode	Zeigt an ob die Nachricht als Unicode oder GSM verschickt wurde	boolean

numchars	Zeigt an wieviele Zeichen für die SMS verwendet wurden	integer

escapenumchars	Zeigt an wieviele Zeichen escaped werden mussten (und als zwei Zeichen im GSM Format zählten)	integer

smscount	Zeigt an ob die Nachricht zu einer langen SMS zusammengefasst wurde und aus wievielen SMS-Längen sie besteht	integer

charge	Zeigt an wieviel für diese SMS berechnet wurde	float

balance	Zeigt das Rest-Guthaben im verwendeten Konto an	float

callbackurl	Rückruf-URL an welche Status-Aktualisierungen und Sendeberichte für diese Nachricht gesendet werden.	string

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

210	Die Rufnummer scheint ungültig zu sein

211	Der message Parameter enthält keinen Text

212	Der message Parameter ist zu lang

213	Der unicode Parameter ist true aber der message parameter wurde nicht in UCS2-Notation übergeben

214	Der unicode Parameter ist false aber die Nachricht wurde in UCS2-Notation übergeben

215	Der unicode Parameter ist false aber die Nachricht enthält Zeichen ausserhalb des GSM7 Alphabets

216	The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).

217	Kurzcode Senderkennungen sind nicht erlaubt

218	Die Rückruf-URL scheint ungültig zu sein

219	Die übergebene Sendezeit scheint ungültig zu sein. Erforderliches Format ist ATOM mit Zeitzone, zum Beispiel: "2011-04-17T17:59:36.67+08" oder "2011-04-17 17:59:36-02"

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

SMS Empfangen API

Rückruf: pushIncomingSms

Falls in dein Posteingangs-Einstellungen eine Rückruf URL angegeben wurde leitet My-Cool-SMS die Nachricht automatisch auf die angegebene URL weiter. Die Rückruf-URL kann mittels Web-Interface in den Posteingangs-Einstellungen gesetzt werden.

Rückruf-Beispiel

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}

Hinweis: Erfahre hier wie JSON Rückrufe am besten verarbeitet werden können.

Rückruf-Parameter

Schlüssel	Beschreibung	Typ

from	Die Senderkennung mit der die SMS verschickt wurde. Kann eine Rufnummer im internationale Format oder eine alphanumerische Zeichenkette mit bis zu elf Zeichen enthalten.	string

fromcountrycode	Enthält das ISO-Format Länderkürzel (zwei Buchstaben) der Senderkennung. Falls die Senderkennung alphanumerisch ist wird hier NULL zurückgegeben.	string(2) \|\| NULL

to	Die Rufnummer an welche die SMS geschickt wurde (deine My-Cool-SMS Online Rufnummer).	string

unicode	Zeigt an ob die Nachricht in Unicode oder GSM gesendet wurde.	boolean

smscount	Zeigt an ob die Nachricht zu einer langen SMS zusammengefasst wurde und aus wievielen SMS-Längen sie besteht	integer

body	Der SMS-Inhalt als Unicode Text-String	string

bodyucs2	Der SMS-Inhalt in UCS2 Bytecode-Notation	string

bodygsm7	Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde)	string

numchars	Zeigt an wieviele Zeichen für die SMS verwendet wurden	integer

escapenumchars	Zeigt an wieviele Zeichen escaped werden mussten (und als zwei Zeichen im GSM Format zählten)	integer

cost	Zeigt an wieviel für diese SMS berechnet wurde	float

Funktion: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing incoming SMS. Can be customized by using the optional parameters.

POST/GET Beispiel

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

virtualnumber	The virtual number for which sms text messages should be fetched	string

Optionale Parameter

Parameter	Beschreibung	Typ

thresholdid	Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0.	integer

limit	The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied.	integer

order	Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC"	string

thresholdoperator	Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt"	string(2)

Antwort bei einem erfolgreichen Aufruf

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "numchars":16,
         "escapechars":0,
         "smscount":1
      }
   ]
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean
total	The total number of messages on this virtual number	integer
fetched	The number of messages that were fetched	integer
maxid	The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages.	integer
messages	Contains an array of SMS text objects (with self-explaining attribute names, see example).	array

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

232	Die Rufnummer scheint ungültig zu sein

233	The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.

234	The provided thresholdid is invalid

235	Ungültiger limit Parameter

236	Invalid order parameter

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Guthaben-Info API

Funktion: getBalance

Gibt ein JSON Objekt mit dem Restguthaben (oder eine Fehlermeldung) zurück

POST/GET Beispiel

username=xxx&password=yyyy&function=getBalance

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "balance":752.210
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

balance	Verbleibendes Rest-Guthaben in Euro	float

Sendebericht API

Sendebericht können in My-Cool-SMS auf zwei Art und Weisen empfangen werden. Zum einen kann der My-Cool-SMS Server mit getDeliveryReport gepollt werden und zum anderen können HTTP Rückrufe in Echtzeit via pushDeliveryReport empfangen werden. Bitte beachte dabei dass Sendeberichte für Mailings nur mit getDeliveryReport verfügbar sind.

Funktion: getDeliveryReport

Gibt einen Sendebericht für eine einzelne SMS (die mit sendSms verschickt wurde) oder einen Sendebericht für ein Mailing zurück. Falls ein Mailing-Listen Sendebericht angefordert wird muss der optionale groupkey Parameter auf true gesetzt werden. Das zurückgegebene JSON-Objekt kann in diesem Fall eine kompakte Zusammenfassung enthalten oder einen detaillierten Bericht für jeden einzelnen Abonennten (indem der optionale Parameter mailingdetails auf true gesetzt wird).

POST/GET Beispiel

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

id	Referenz-ID. Entweder eine SMS ID (wie von sendSms zurückgegeben) oder ein Mailing-Gruppenschlüssel (wie von sendMailing zurückgegeben). Falls ein Mailing-Gruppenschlüssel verwendet wird muss der optionale Parameter groupkey auf true gesetzt werden.	string

Optionale Parameter

Parameter	Beschreibung	Typ

groupkey	Muss auf true gesetzt werden falls ein Gruppenschlüssel als id Parameter verwendet wird (und ein Sendebericht für ein Mailing zurückgegeben werden soll). Ist auf false voreingestellt.	string

mailingdetails	Muss auf true gesetzt werden falls, zusätzlich zur kompakten Zusammenfassung, ein detaillierter Sendebericht für jeden einzelnen Abonennten zurückgegeben werden soll. Ist auf false voreingestellt.	string

Antwort bei einem erfolgreichen Aufruf: groupkey=false (Voreinstellung)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

Rückgabewerte bei einem erfolgreichen Aufruf: groupkey=false (Voreinstellung)

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

smsid	Die Referenz-ID für diesen Sendebericht	string

status	Zeigt den Status dieser SMS an	string

Hinweis: Erfahre mehr über mögliche Status-Codes.

Antwort bei einem erfolgreichen Aufruf: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}

Hinweis: Erfahre mehr über mögliche Status-Codes.

Antwort bei einem erfolgreichen Aufruf: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}

Hinweis: Erfahre mehr über mögliche Status-Codes.

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

223	Unbekannte SMS ID

224	Unbekannter Gruppenschlüssel

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: getRecentReports

Gibt ein JSON-Objekt mit Sendeberichten für die am neulichsten versendeten SMS zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=getRecentReports&limit=10

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

limit	Gibt an wieviele Sendeberichte zurückgegeben werden sollen.	integer

Antwort bei einem erfolgreichen Aufruf

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

number	Ziel-Rufnummer	string

senderid	Die Senderkennung mit der die Nachricht versendet wurde.	string

body	Der SMS-Inhalt als Unicode Text-String	string

bodyucs2	Der SMS-Inhalt in UCS2 Bytecode-Notation	string

bodygsm7	Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde)	string

unicode	Zeigt an ob die Nachricht als Unicode oder GSM verschickt wurde	boolean

timesent	Der Zeitpunkt zu dem die Nachricht versendet wurde.	timestamp with time zone

status	Zeigt den Status dieser SMS an	string

Hinweis: Erfahre mehr über mögliche Status-Codes.

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

225	Ungültiger limit Parameter

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Rückruf: pushDeliveryReport

Falls der callbackurl Parameter im Aufruf der sendSms-Funktion gesetzt wurde, gibt My-Cool-SMS automatisch (und in Echtzeit) einen Sendebericht an die angegebene URL zurück. Der Rückruf wird immer als JSON Objekt in der HTTP Raw-Data gesendet.

Rückruf-Beispiel

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}

Hinweis: Erfahre hier wie JSON Rückrufe am besten verarbeitet werden können.

Rückruf-Parameter

Schlüssel	Beschreibung	Typ

smsid	Die Unique ID der SMS für welche der Rückruf bedeutsam ist. Der smsid Parameter wurde ursprünglich in der Antwort auf den sendSMS Funktionsaufruf zurückgegeben.	string(32)

status	Zeigt den Status dieser SMS an	string

Status-Referenz

Status	Beschreibung

SMS_STATUS_QUEUED	In Warteschleife - Diese Nachricht ist in der Wartseschleife und wurde noch nicht verschickt.

SMS_STATUS_AT_CARRIER	Beim Mobilfunkbetreiber - Die SMS wurde and den Mobilfunkbetreiber gesendet und sollte als 'Zugestellt' markiert werden sobald sie auf dem Mobiltelefon eingeht. Bitte beachte dass manche Mobilfunkanbieter keinen Sendebericht zur Verfügung stellen. In diesem Fall wird die Nachricht als 'Beim Mobilfunkanbieter' angezeigt obwohl sie auf dem Mobiltelefon eingegangen ist.

SMS_STATUS_DELIVERY_DELAYED	Zustellung verzögert - Die Zustellung der Nachricht verzögert sich.

SMS_STATUS_DELIVERED	Zugestellt - Die Nachricht wurde erfolgreich zugestellt.

SMS_STATUS_BOUNCED	Nicht zugestellt - Diese Nachricht konnte vom Mobilfunkbetreiber des Empfängers nicht zugestellt werden. Mögliche Gründe sind eine ungültige Nummer oder Sender ID, das Telefon sich ausserhalb des Mobilfunknetzes befindet oder Datenstaus beim Mobilfunkbetreiber.

SMS_STATUS_EXPIRED	Abgelaufen - Die Zustellungs-Phase für diese Nachricht ist abgelaufen und die SMS konnte nicht zugestellt werden. Dies geschieht normalerweise wenn das Ziel-Telefon abgelaufen ist oder sich zu lange ausser Netzwerk-Reichweite befindet.

SMS_STATUS_ERROR	Fehlgeschlagen - Die Zustellung ist fehlgeschlagen (dein Konto wurde nicht belastet). Mögliche Gründe sind eine uns unbekannte Vorwahl or temporäre Netzwerkprobleme. Bitte kontaktiere den My-Cool-SMS Support falls die verwendete Nummer mit Sicherheit korrekt ist.

Mailing-Listen API

Funktion: sendMailing

Sendet eine SMS Text Nachricht an eine My-Cool-SMS Mailing-Liste. Mailing-Listen können über das Web Interface erstellt und verwaltet werden.

Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

uniqueid	Die Unique ID der Mailing-Liste. Die Unique IDs für alle Mailing-Listen können im Web Interface unter "Verwalten" der jeweiligen Mailing-Liste eingesehen werden.	string

message	The SMS Inhalt. My-Cool-SMS erkennt automatisch ob es sich um eine Unicode oder GSM Nachricht handelt und versendet die SMS im jeweiligen Format. Der Uniocde Parameter kann benutzt werden um eine bestimmte Kodierung zu erzwingen. Falls Unicode auf true gesetzt wird muss der SMS Inhalt in UCS2 Notation übergeben werden. Wenn Unicode auf false gesetzt ist, wird die Nachricht im GSM Standard versendet und darf nur Zeichen aus dem GSM7 Alphabet enthalten. Lange Nachrichten werden automatisch konkateniert (bis zu fünf Nachrichten oder 765 Zeichen für GSM bzw. 335 Zeichen für Unicode SMS). Bitte beachte dass der Unicode Paramater bei Aufrufen mit der GET Methode immer verwendet werden sollte, da es in diesem Fall nicht möglich ist automatisch zwischen Unicode und GSM zu unterscheiden.	string

Hinweis: Erfahre mehr über GSM, Unicode und UCS2.

Optionale Parameter

Parameter	Beschreibung	Typ

unicode	Erzwingt eine Unicode oder GSM Kodierung der SMS. Falls true verwendet wird muss der SMS Inhalt mit UCS2 Notation übergeben werden. Falls auf false gesetzt darf der SMS Inhalt lediglichen Zeichen aus dem GSM7 Alphabet enthalten. Ist auf NULL voreingestellt und erkennt in diesem Fall die zu verwendende Kodierung automatisch.	boolean

senderid	Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789 Alternativ darf eine alphanumerische Zeichenkette mit bis zu 11 Zeichen verwendet werden, z.B. "Firmenname"	string

scheduletime	Versendet die Nachricht zu einem bestimmten Zeitpunkt. Erfordert einen Timestamp im ATOM Format (mit Zeitzone), zum Beispiel: "2011-04-17T17:59:36.67+08" oder "2011-04-17 17:59:36-02"	timestamp with time zone

Hinweis: Erfahre mehr über Sendebericht Rückrufe.

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

groupkey	Eindeutiger Schlüssel für dieses Mailing. Sollte auf Client-Seite zur späteren Referenz (Sendeberichte) gespeichert werden.	string(32)

body	Der SMS-Inhalt als Unicode Text-String	string

bodyucs2	Der SMS-Inhalt in UCS2 Bytecode-Notation	string

bodygsm7	Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde)	string \|\| NULL

uniqueid		string(7)

senderid	Zeigt an ob die Ziel-Rufnummer dynamische Senderkennungen unterstützt	boolean

unicode	Zeigt an ob die Nachricht als Unicode oder GSM verschickt wurde	boolean

numchars	Zeigt an wieviele Zeichen für die SMS verwendet wurden	integer

escapenumchars	Zeigt an wieviele Zeichen escaped werden mussten (und als zwei Zeichen im GSM Format zählten)	integer

smscount	Zeigt an ob die Nachricht zu einer langen SMS zusammengefasst wurde und aus wievielen SMS-Längen sie besteht	integer

subscribers	Die Anzahl der Empfänger dieses Mailings.	integer

charge	Zeigt an wieviel für diese SMS berechnet wurde	float

balance	Zeigt das Rest-Guthaben im verwendeten Konto an	float

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

220	Ungültige Unique ID

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: addSubscriber

Fügt der Mailing-Liste einen neuen Abonennten hinzu. Falls die übergebene Rufnummer bereits in der List existiert wird der bestehende Eintrag überschrieben.

Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

number	Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789	string

uniqueid	Die Unique ID der Mailing-Liste. Die Unique IDs für alle Mailing-Listen können im Web Interface unter "Verwalten" der jeweiligen Mailing-Liste eingesehen werden.	string

Optionale Parameter

Parameter	Beschreibung	Typ

title	Anrede des Abonennten	varchar(16)

firstname	Vorname des Abonennten	varchar(32)

lastname	Nachname des Abonennten	varchar(32)

company	Firma des Abonennten	varchar(64)

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

number	Normalisierte Rufnummer der neuen Abonennten	string

title	Anrede des neuen Abonennten	string

firstname	Vorname des neuen Abonennten	string

lastname	Nachname des neuen Abonennten	string

company	Firma des neuen Abonennten	string

subscribercost	Kosten pro Nachricht an diesen Abonennten	float

senderidenabled	Zeigt an ob die Ziel-Rufnummer dynamische Senderkennung unterstützt	boolean

maxcharsgsm	Zeigt an wieviele Zeichen pro Nachricht an diesen Abonenntent verschickt werden können	integer

maxcharsunicode	Zeigt an ob die Rufnummer des Abonennten Unicode Nachrichten unterstützt	integer

countrycode	Das Länderkürzel des Abonennten (Zwei Buchstaben ISO-Standard Format)	string(2)

mailinglistcost	Die neuen Gesamtkosten pro Mailing an diese Liste.	float

mailinglistsubscribers	Die neue Anzahl von Abonennten auf dieser Mailing-Liste.	integer

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

221	Eingabe für {field} is zu lang.

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: updateSubscriber

Siehe Funktion: addSubscriber

Funktion: deleteSubscriber

Entfernt einen Abonennten aus der Mailing-Liste. Verwendet die Rufnummer als Referenz-Schlüssel.

Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

uniqueid	Die Unique ID der Mailing-Liste. Die Unique IDs für alle Mailing-Listen können im Web Interface unter "Verwalten" der jeweiligen Mailing-Liste eingesehen werden.	string

number	Die Rufnummer des zu löschenden Abonennten	string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

number	Die normalisierte Rufnummer des gelöschten Abonennten	string

mailinglistcost	Die neuen Gesamtkosten pro Mailing an diese Liste.	float

mailinglistsubscribers	Die neue Anzahl von Abonennten auf dieser Mailing-Liste.	integer

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

220	Ungültige Unique ID

222	Die Mailing-Liste enthält keinen Abonennten mit dieser Rufnummer

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Werkzeuge API

Funktion: doHlrLookup

Führt einen Home Location Resgister (HLR) Lookup für einen Rufnummer aus und gibt die relevanten MSC, MCC, MNC, INSI sowie Informationen über den Mobilfunkbetreiber zurück und gibt an ob die Rufnummer derzeit Roaming ist (das Telefon sich im Ausland befindet) und ob es sich um eine portierte Nummer handelt (die urprünglich bei einem anderen Mobilfunkbetreiber registriert war).

Hinweis: Erfahre mehr über HLR, IMSI, MCC, MNC und MSC.

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

number	Die Rufnummer für die der HLR Lookup ausgeführt werden soll. Internationales Format, zum Beispiel: 49123456789 oder +49123456789 oder 0049123456789	string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

status	Zeigt den Status des Lookups an. Bitte verwende die HLR Status-Referenz für weitere Informationen.	string

number	Die Rufnummer für die der HLR Lookup ausgeführt wurde.	string

imsi	International Mobile Subscriber Identity (IMSI). Eindeutige ID der Rufnummer (befindet sich auf der SIM Karte).	string

mcc	Der Mobile Countrz Code (MCC)	string

mnc	Der Mobile Network Code (MNC). Kann entweder zwei Zeichen (Europäischer Standard) oder drei Zeichen (Nord-Amerikanischer Standard) enthalten.	string

msin	Die Mobile Subscription Identification Number (MSIN) in der Kundendatenbank des Mobilfunkbetreibers zu dem diese Rufnummer gehört.	string

servingmsc	Das Mobile Switching Center (MSC) über die SMS an diese Rufnummer geroutet werden.	string

servinghlr	Das Home Location Register (HLR) in dem die Rufnummer abgelegt ist.	string

originalnetworkname	Der Mobilfunkbetreiber zu dem diese Rufnummer gehört (oder ursprünglich gehört hat, falls es sich hierbei um eine portierte Nummer handelt).	string

originalnetworkprefix	Die Vorwahl des Mobilfunknetzwerkes zu dem diese Nummer gehört (oder ursprönglich gehört hat, falls es sich um eine portierte Nummer handelt).	string

originalcountryname	Das Land zu dem diese Rufnummer gehört.	string

originalcountrycode	Das ISO-Länderkürzel (zwei Zeichen) zu dem diese Rufnummer gehört.	string

originalcountryprefix	Die Vorwahl des Landes zu dem diese Rufnummer gehört.	string

roamingcountryname	Das Land in dem diese Rufnummer derzeit gehostet wird (Roaming).	string

roamingcountrycode	Das ISO-Länderkürzel (zwei Zeichen) des Landes in dem diese Rufnummer derzeit gehostet wird (Roaming).	string

roamingcountryprefix	Die Vorwahl des Landes in dem diese Rufnummer derzeit gehostet wird (Roaming).	string

roamingnetworkname	The network the cell phone is currently roaming with	string

portednetworkname	The network the number has been ported to	string

isported	Zeigt an ob es sich um eine portiere Nummer handelt	boolean

iscorrect	Zeigt an ob die angegebene Rufnummer gültig ist	boolean

isroaming	Zeigt an ob diese Rufnummer derzeit in einem Gastland gehostet wird (Roaming).	boolean

charge	Die Kosten die für diesen HLR Lookup berechnet wurden (0.01 EUR).	numeric

Hinweis: Erfahre mehr über HLR, IMSI, MCC, MNC und MSC.

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

210	Die Rufnummer scheint ungültig zu sein

226	HLR Lookup fehlgeschlagen.

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

HLR Status-Referenz

Status	Beschreibung

HLR_STATUS_UNKNOWN_NUMBER	Die Nummer existiert nicht oder konnte in keinem HLR gefunden werden. SMS an diese Rufnummer kommen nicht an.

HLR_STATUS_OK	Diese Nummer existiert und der HLR Lookup war erfolgreich. SMS an diese Rufnummer werden normal zugestellt.

HLR_STATUS_NOT_OK	Die Rufnummer befindet sich seit langer Zeit ausser Netzwerk-Reichweite oder wurde vom Mobilfunkbetreiber deaktiveiert. SMS an diese Rufnummer können nicht zugestellt werden.

HLR_STATUS_FAILED	HLR Lookup fehlgeschlagen.

Funktion: toUCS2

UCS2-kodiert einen String

Wichtig: toUCS2 muss über JSON aufgerufen werden.

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

number	Die Rufnummer für die der HLR Lookup ausgeführt werden soll. Internationales Format, zum Beispiel: 49123456789 oder +49123456789 oder 0049123456789	string

Optionale Parameter

Parameter	Beschreibung	Typ

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

ucs2	Der übergebene String in UCS2-Notation	string

Funktionsspezifische API Fehler

Kein(e)

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: fromUCS2

Dekodiert einen UCS2 String

POST/GET Beispiel

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

Erforderliche Parameter

Parameter	Beschreibung	Typ

str	Der zu dekodierende UCS2 String	string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "decoded":"繁体中文"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

decoded	Der dekodierte UCS2 String in Unicode	string

Funktionsspezifische API Fehler

Fehlercode	Fehlerbeschreibung

201	Ungültige UCS2 Eingabe

Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Fehlerberichte

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

Antwort bei einem fehlerhaften Aufruf

{
    "success":false,
    "errorcode":103,
    "errordescription":"Ein erforderlicher Parameter fehlt: senderid"
}

Rückgabewerte bei einem fehlerhaften Aufruf

Schlüssel	Beschreibung	Typ

success	Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte.	boolean

errorcode	Fehlercode (bestehend aus drei Nummern)	string(3)

errordescription	Fehlerbeschreibung	string

Funktionsspezifische API Fehler

Manche Funktionen haben spezifische Fehlercodes die nur von der jeweiligen Funktion zurückgegeben werden. Diese Art von Fehlercode hat das Format 2xx und ist in der Dokumentation für die jeweilige Funktion beschrieben.

Allgemeine API Fehler

Jede Funktion kann Funktionsspezifische Fehler, aber auch allgemeine API Fehler mit dem Fehlercode-Format 1xx, zurückgeben.

Allgemeine Fehlercodes

Fehlercode	Fehlerbeschreibung

101	Login fehlgeschlagen. Falscher Benutzername oder Passwort.

102	Dieser Account wurde noch nicht freigeschaltet.

103	Ein erforderlicher Parameter fehlt

104	Ungültiger Aufruf. Keine GET, POST oder gültige JSON Eingabe gefunden.

105	Unbekannte Funktion

106	Zugriff verweigert

107	Allgemeiner API Fehler

108	Ungültige Aufrufs-Struktur

109	Guthaben reicht nicht aus

Haben wir etwas vergessen? Gibt es Fragen? Vorschläge oder Ideen was noch hinzugefügt werden sollt? Fall ja, lass es uns bitte wissen!

		English

		Español

		Français

		Nederlands

		Polski

		Português

		Руccкий

		繁体中文

SMS Programmierschnittstelle (SMS API)

Gibt es Fragen?

SMS Senden API

Funktion: sendSms

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Optionale Parameter

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Funktionsspezifische API Fehler

SMS Empfangen API

Rückruf: pushIncomingSms

Rückruf-Beispiel

Rückruf-Parameter

Funktion: getIncomingSms

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Optionale Parameter

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Funktionsspezifische API Fehler

Guthaben-Info API

Funktion: getBalance

POST/GET Beispiel

JSON Beispiel

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Sendebericht API

Funktion: getDeliveryReport

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Optionale Parameter

Antwort bei einem erfolgreichen Aufruf: groupkey=false (Voreinstellung)

Rückgabewerte bei einem erfolgreichen Aufruf: groupkey=false (Voreinstellung)

Antwort bei einem erfolgreichen Aufruf: groupkey=true

Antwort bei einem erfolgreichen Aufruf: groupkey=true&mailingdetails=true

Funktionsspezifische API Fehler

Funktion: getRecentReports

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Funktionsspezifische API Fehler

Rückruf: pushDeliveryReport

Rückruf-Beispiel

Rückruf-Parameter

Status-Referenz

Mailing-Listen API

Funktion: sendMailing

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Optionale Parameter

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Funktionsspezifische API Fehler

Funktion: addSubscriber

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Optionale Parameter

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Funktionsspezifische API Fehler

Funktion: updateSubscriber

Funktion: deleteSubscriber

POST/GET Beispiel

JSON Beispiel

Erforderliche Parameter

Antwort bei einem erfolgreichen Aufruf

Rückgabewerte bei einem erfolgreichen Aufruf

Funktionsspezifische API Fehler

Werkzeuge API

Funktion: doHlrLookup

JSON Beispiel

Erforderliche Parameter