Mail-2-SMS-Schnittstelle - der

der-gateway.de
Qualität und Zuverlässigkeit seit 2005!
Ihre SMS in guten Händen!
MailMail-2-SMS
QUALITÄT & ZUVERLÄSSIGKEIT SEIT 2005
Themenübersicht
G ATEW AY ANB INDUNG
F UNK TIO NE N
S MS VE RSA ND
Seit dem Jahr 2005 steht bei uns die Qualität
Durch diese Techniken bieten wir unseren
und die Zuverlässigkeit an erster Stelle! In re-
Kunden
gelmäßigen Abständen werden unsere Netze
Stabilität!
den
optimalen
Schutz
und
durch unsere eigenen Systeme geprüft und im
Fehlerfall
EI NGABEW ERTE
RÜCKGAB EW ERT E
A L LGE MEI NES
defekte
Routen
umgeleitet.
Auch bei der Wahl unserer Partner setzen
Nicht nur unsere Netze werden überwacht,
wir auf höchste Qualität und Zuverlässigkeit,
auch unsere Server sind so ausgelegt, dass im
denn nur so können wir die Stabilität
Fehlerfall ein Backupsystem die komplette
gewährleisten.
Leistung übernehmen kann.
der-gateway. de
Rausch-Dalle-Wehr GbR
Roermonder Straße 555
52072 Aachen
E-Mail:
[email protected]
[email protected]
VERSION 2.41
-
07.02.2014
der-gateway.de
Mail-2-SMS - Schnittstellenbeschreibung |
2
Einleitung
In dieser Dokumentation wollen wir Ihnen unsere Mail-2-SMS-Schnittstelle erläutern. Diese Schnittstelle ist für die
Übertragung von einzelnen SMS-Nachrichten per E-Mail an unseren Gateway gedacht. Diese Schnittstelle ist auf
Grund der Beschaffenheit nur auf ca. 10 SMS pro Sekunde ausgelegt. Sollten Sie mehr als diese Anzahl an SMS pro
Sekunde versenden, so werden diese bei uns zwischen gespeichert und nach und nach (first-in first-out) abgearbeitet.
Sollte Ihre Versandmenge dauerhaft diese Grenze überschreiten, so sprechen Sie uns bitte auf andere Schnittstellen
an.
INHALTSVERZEICHNIS
Einleitung
2
Allgemeine Parameter
3
Gateway Anbindung
Schnittstellen Funktionen
SMS Versand
Eingabe - / Rückgabewerte
3
4
4
5
Eingabewerte
5
Rückgabewerte
6
Allgemeines
7
SMS mit Überlänge
7
Wir sagen Danke!
7
der-gateway.de
Mail-2-SMS - Schnittstellenbeschreibung |
3
Allgemeine Parameter
Gateway-Anbindung
Für die Anbindung des Mail-2-SMS Gateway bieten wir Ihnen eine Standard EMailadresse an. Zum duchführen des SMS-Versandes muss dann nur noch eine
E-Mail an diese Adresse mit den unten beschrieben Inhalten gesandt werden.
GATEWAY-ADRESSE
[email protected]
Hinweis:
Bitte beachten Sie, dass die E-Mails, welche Sie an unseren Gateway versenden
im Standard Text versandt werden müssen und nicht als HTML Mail!
Des Weiteren möchten wir Sie darüber informieren, dass unser Mail-2-SMS
Gateway automatisch auch SPAM-Absender, über die bekannten Listen,
automatisch blockt. Dies müssen wir leider machen, um unnötigen Traffic auf
dem Gateway zu vermeiden.
Warum Mail-2-SMS?
SCHNELLE UND EINFACHE
ANBINDUNG
Viele Systeme haben eine schnelle
Anbindung für den Mailversand. Um hier
große Veränderungen für Ihr System zu
minimieren, bieten wir Ihnen somit eine
schnelle Möglichkeit der Anbindung an einen
SMS Gateway.
der-gateway.de
Mail-2-SMS - Schnittstellenbeschreibung |
4
Funktionen
Funktionsbeispiele
SMS Versand
An Hand dieser Funktion können Sie einzelne SMS versenden.
Jeder dieser Parameter muss durch ein „~+~“ vom nachfolgenden Parameter
getrennt werden.
PARAMETERNAME
username
password
ERLÄUTERUNG
Bitte geben Sie hier Ihren Benutzernamen für die SMSSchnittstelle an. Es kann sein, dass dieser Benutzername vom
Webportal abweichend ist.
Bitte geben Sie hier Ihr Passwort für die SMS-Schnittstelle an.
Beachten Sie bitte auch hier, dass dieses Passwort, wie der
Benutzername, abweichend vom Webportal sein kann.
api_key
Um fremde Zugriffe vermeiden zu können, müssen Sie
zusätzlich zu Ihrem Passwort noch den API-Key angeben.
Erst die Kombination aus Benutzername, Passwort und APIKey ermöglichen die Authentifizierung an der Schnittstelle.
gateway
Mit diesem Parameter können Sie zwischen den
unterschiedlichen Gatewayarten von uns wählen.
Mögliche Parameter:
message_sender
10
Route BASIC
20
Route BEST PRICE
30
Route BEST QUALITY
Hier muss Ihre Absenderkennung angegeben werden. Diese
Kennung kann entweder aus einer 16stelligen Nummer oder
aus einer 11stelligen Alpha-numerischen Zeichenfolge
bestehen.
Es sind keine Umlaute, Sonder- oder Leerzeichen
zugelassen.
message_receiver
message_text
In diesem Feld muss der Empfänger angegeben werden.
Hierbei muss beachtet werden, dass die Rufnummer des
Empfängers im internationalen Standardformat übergeben
werden muss. (z.B. für Deutschland 004917012345678)
Hier muss der Nachrichtentext eingetragen werden. Der
Nachrichtentext muss in URL-encoded ISO-8859-15 oder
UTF-8 formatiert sein.
message_time
(Dieses Feld ist optional)
Hiermit können Sie einen zeitversetzten Versand einstellen.
Bitte geben Sie das Datum ISO 8601 (YYYY-MM-DDThh:mm)
an. (z.B. 2014-02-17T09:52:12)
message_status_url
(Dieses Feld ist optional)
Wenn Sie über den Status und jede Statusänderung der SMS
automatisch von unserem System informiert werden wollen,
so müssen Sie in diesem Parameter die URL Ihrer
Schnittstelle zur Statusverarbeitung mitteilen.
Die Variable, welche unsere SMS Gateway mit dem
Nachrichtenstatus befüllen soll, bitte mit einem %status%
kennzeichnen. (siehe Aufruf-Beispiel)
BEISPIEL BETREFF
username=testuser~+~password=testpass
wort~+~api_key=AUend73hdnLanfIK98d0
0293~+~gateway=20~+~message_sender
=DerGateway~+~message_receiver=0049
12345678
BEISPIEL BETREFF MIT AUTOMATISCHEM
STATUS-REPORT
username=testuser~+~password=testpass
wort~+~api_key=AUend73hdnLanfIK98d0
0293~+~gateway=20~+~message_sender
=DerGateway~+~message_receiver=0049
12345678~+~message_status_url=http://I
hreDomain.tld/sms_status_return.php?sta
tus=%status%&message_id=12345
(Sollten Sie eine eigene Message-ID in Ihrem
System verwenden, so können Sie diese
anstelle der 12345 angeben. Sollten Sie aber
unsere Message-ID als Rückgabe erhalten
wollen, so geben Sie bitte %msg_id%
anstelle der 12345 an.
Wenn Ihr Server einmal nicht erreichbar ist,
wird der Status erst 15, dann 30, dann 60,
dann 180, dann 360, dann 720 und 1440
Minuten später noch einmal versucht zu
übertragen. Erst dann wird die Übermittlung
bei uns für diesen Status als „fehlerhaft“
beendet!)
BEISPIEL MAILTEXT
Das ist eine Beispiel SMS
der-gateway.de
Mail-2-SMS - Schnittstellenbeschreibung |
5
Eingabe- / Rückgabewerte
Bei den Eingabe - / Rückgabewerten gehen wir nur auf die Werte ein, welche zusätzlich zu den Standardparametern
verwendet werden können / müssen.
An Hand der Parametergruppe können Sie erkennen, welche Parameter zusammen aufgeführt werden müssen. Durch
das Kennzeichen P (Pflicht) und O (Optional) können Sie des Weiteren erkennen, ob dieser Parameter in der Gruppe
verpflichtend ist.
Eingabewerte
PARAMETERNAME
PARAMETERGRUPPE
ERLÄUTERUNG
username
P
login
Bitte geben Sie hier Ihren Benutzernamen für die SMS-Schnittstelle an. Es
kann sein, dass dieser Benutzername vom Webportal abweichend ist.
password
P
login
Bitte geben Sie hier Ihr Passwort für die SMS-Schnittstelle an.
Beachten Sie bitte auch hier, dass dieses Passwort, wie der Benutzername,
abweichend vom Webportal sein kann.
api_key
P
login
Um fremde Zugriffe vermeiden zu können, müssen Sie zusätzlich zu Ihrem
Passwort noch den API-Key angeben.
Erst die Kombination aus Benutzername, Passwort und API-Key ermöglichen
die Authentifizierung an der Schnittstelle.
gateway
P
sms_sending
Mit diesem Parameter können Sie zwischen den unterschiedlichen
Gatewayarten von uns wählen
Mögliche Parameter:
10
Route BASIC
20
Route BEST PRICE
30
Route BEST QUALITY
message_sender
P
sms_sending
Hier muss Ihre Absenderkennung angegeben werden. Diese Kennung kann
entweder aus einer 16stelligen Nummer oder aus einer 11stelligen Alphanumerischen Zeichenfolge bestehen.
Es sind keine Umlaute, Sonder- oder Leerzeichen zugelassen
message_receiver
P
sms_sending
In diesem Feld muss der Empfänger angegeben werden. Hierbei muss
beachtet werden, dass die Rufnummer des Empfängers im internationalen
Standardformat übergeben werden muss. (z.B. für Deutschland
004917012345678)
Sollten Sie Bulk- / Massen-SMS versenden wollen, so können Sie im
Parameter MESSAGE_RECEIVER die Rufnummern der Empfänger durch ein
„;“ Trennzeichen trennen. (z.B.: 004917012345678;004917087654321;0049….)
(Bitte beachten Sie, dass die HTTP-Schnittstelle für 200 SMS / Sekunde für Sie ausgelegt ist
und wir hierdurch bei dieser Schnittstelle die Bulk-SMS auf 200 Empfänger je Aufruf
begrenzen müssen. Bei HTTPS vermindert sich dies auf 100!)
message_text
P
sms_sending
Hier muss der Nachrichtentext eingetragen werden. Der Nachrichtentext
muss in URL-encoded ISO-8859-15 oder UTF-8 formatiert sein.
message_time
O
sms_sending
Hiermit können Sie einen zeitversetzten Versand einstellen. Bitte geben Sie
das Datum ISO 8601 (YYYY-MM-DDThh:mm) an. (z.B. 2014-02-17T09:52:12)
message_status_url
O
sms_sending
Wenn Sie über den Status und jede Statusänderung der SMS automatisch
von unserem System informiert werden wollen, so müssen Sie in diesem
Parameter die URL Ihrer Schnittstelle zur Statusverarbeitung mitteilen.
Die Variable, welche unsere SMS Gateway mit dem Nachrichtenstatus
befüllen soll, bitte mit einem %status% kennzeichnen. (siehe Aufruf-Beispiel)
der-gateway.de
Mail-2-SMS - Schnittstellenbeschreibung |
6
Rückgabewerte
Bitte beachten Sie, dass wir Ihnen bei der Mail-2-SMS Schnittstelle nicht direkt per E-Mail eine Rückmeldung
geben können. Sie können aber in jeder E-Mail eine Status URL festlegen, über welche wir Ihnen die
unterschiedlichen Status zurückmelden können.
RÜCKGABECODE
101
RÜCKGABEGRUPPE
Benutzer
ERLÄUTERUNG
Benutzername und / oder Passwort wurden nicht gesetzt
102
Benutzer
Benutzername nicht gesetzt
103
Benutzer
Passwort nicht gesetzt
104
Benutzer
Logindaten nicht korrekt
105
Benutzer
API-Key wurde nicht gesetzt
106
Benutzer
Der Benutzeraccount ist gesperrt
110
sms_sending
Absenderkennung wurde nicht gesetzt
111
sms_sending
Absenderkennung für eine nummerische Absenderkennung zu lang
112
sms_sending
Absenderkennung für eine alphanummerische Absenderkennung zu lang
113
sms_sending
Absenderkennung ungültig (allgemeiner Fehler)
114
sms_sending
Empfängerkennung wurde nicht gesetzt
115
sms_sending
Empfängerkennung ohne Länderkennung
116
sms_sending
Empfängerkennung darf nur aus Zahlen bestehen
117
sms_sending
Empfängerkennung ungültig (allgemeiner Fehler)
118
sms_sending
Nachrichtentext wurde nicht gesetzt
119
sms_sending
Der Nachrichtentext ist falsch codiert
120
sms_sending
Es wurden zu viele Empfänger für den Bulk- / Massen SMS Versand angegeben.
121
sms_sending
Datum ungültig
122
sms_sending
Datumsformat ungültig
123
sms_sending
Zeit liegt zu weit in der Vergangenheit (max. 30 Minuten)
124
sms_sending
Zeit liegt zu weit in der Zukunft (max. 13 Monate)
140
sms_sending
Nachricht wurde gespeichert und wird zum übermittelten Zeitpunkt versendet
150
sms_sending
Nachricht wurde erfolgreich an den Gateway übermittelt
901
allgemein
Kontodeckung für die Übermittlung der SMS nicht ausreichend
902
allgemein
Preis konnte nicht ermittelt werden
911
allgemein
Es wurde keine Action an den Gateway übermittelt
997
allgemein
Interner Fehler beim HLR aufgetreten, bitte informieren Sie unseren Support
998
allgemein
externer Fehler (im Operator-Netzwerk), bitte informieren Sie unseren Support
999
allgemein
Interner Fehler, bitte informieren Sie unseren Support
der-gateway.de
Mail-2-SMS - Schnittstellenbeschreibung |
7
Allgemeines
SMS mit Überlänge
Sollten Sie die Feldlänge von 160 Zeichen überschreiten, so wird aus der normalen SMS eine mehrteilige SMS. Um die
Koordination der Nachrichten sicherstellen zu können, gibt es bei den mehrteiligen SMS sogenannte
Steuerkennzeichen, welche sicherstellen, dass die Nachricht auf dem Handy des Empfängers wieder korrekt
zusammengesetzt werden kann. Durch diese Steuerkennzeichen gehen jedoch leider 7 Zeichen bei jeder SMS
verloren, daher gibt es bei mehrteiligen SMS diese folgenden Zeichenlängen zu beachten.
160 Zeichen
160 Zeichen (+0 Steuerzeichen)
Preis 1 SMS
306 Zeichen
306 Zeichen (+14 Steuerzeichen)
Preis 2 SMS
459 Zeichen
459 Zeichen (+21 Steuerzeichen)
Preis 3 SMS
612 Zeichen
612 Zeichen (+28 Steuerzeichen)
Preis 4 SMS
765 Zeichen
765 Zeichen (+35 Steuerzeichen)
Preis 5 SMS
…
…
…
Wir sagen Danke!
Wir danken Ihnen sehr für Ihr Vertrauen!
Sollten Sie Funktionen vermissen, oder sollten Sie Anregungen haben, so sind wir für jegliche Anregungen offen!
Sollten Sie Fragen zur Umsetzung haben oder sollten Sie selber Probleme bei der Einrichtung der Schnittstelle haben,
so zögern Sie nicht, mit uns in Kontakt zu treten.
[email protected]