<< Zurück zu SMSout.de

SMS in eigenen Anwendungen erstellen und versenden (SMS API)

Für den Versand von Einzel-SMS in eigenen Anwendungen, entwickelt z.B. in Borland Delphi, PHP, C++, Java usw., ist ein einfacher HTTP-Aufruf notwendig. Es ist ebenfalls möglich über die Mail2SMS-Schnittstelle Einzel-SMS per E-Mail zu versenden.

Guthaben und aktuelles SMS-Paket abfragen

Mit Hilfe des Scripts sendsms.php kann ebenfalls das eigene Guthaben abgefragt werden. Infos dazu finden Sie am Ende dieser Seite.

Verwendung von Sonderzeichen

Beachten Sie bitte folgende Regeln zur Verwendung von Sonderzeichen:

• Eine SMS sollte immer mit einem Buchstaben (A-Z, a-Z) oder Ziffer (0-9) beginnen, auf keinen Fall Sonderzeichen oder Umlaute verwenden.
• Verzichten Sie so weit es geht auf Sonderzeichen, da diese nicht auf allen Handys korrekt dargestellt werden. Empfohlen ist die Verwendung der Zeichen A-Z 0-9 , + _ : . z.B. die Zeichen <> {[]}²³§%$& @ € sind problematisch.
• Die Verwendung von Hochkommas ' oder ` ´ ist nicht gestattet, diese werden aus Sicherheitsgründen entfernt.
• Alle übergebenen Zeichen müssen iso-8859-1 codiert übergeben werden, nicht im Unicode/UTF-8-Format. Werden Zeichen im Unicode/UTF-8-Format übergeben, dann werden Umlaute/Sonderzeichen mit jeweils 2 Zeichen an das Mobiltelefon übermittelt, dies kann die Länge der SMS erheblich beeinflussen und führt zu Problemen beim Lesen der SMS durch den Empfänger. Ist eine Umwandlung UTF-8 nach iso-8859-1 programmiertechnisch nicht möglich, dann verwenden Sie das spezielle Script sendsmsutf8.php, dieses wandelt alle UTF-8 codierten Zeichen in iso-8859-1 vor dem Versand um.

Der HTTP-Aufruf

https://www.smsout.de/client/sendsms.php?APIkey=<API-Key aus dem SMSout.de Kundenbereich>&SMSTo=<rufnummer oder mehrere rufnummern mit semikolon(;) getrennt>&SMSType=<smstype>&SMSText=<smstext 160 Zeichen urlencoded>

Alternativer Aufruf mit Benutzername und Passwort, diese Variante sollte nicht mehr verwendet werden:

https://www.smsout.de/client/sendsms.php?Username=<smsout-username>&Password=<smsout-password>&SMSTo=<rufnummer oder mehrere rufnummern mit semikolon(;) getrennt>&SMSType=<smstype>&SMSText=<smstext 160 Zeichen urlencoded>

Ein Aufruf per http:// ist ebenfalls möglich, falls https:// durch Ihre Anwendung nicht unterstützt wird. Beim Aufruf per https:// wird nur TLS 1.2 und TLS 1.3 unterstützt, keine älteren TLS-Versionen. Beim Fehler "Error connecting with SSL, error: 1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert" wird TLS v1.0 oder v1.1 verwendet, auf TLS v1.2 die eigene Software umstellen.

Die Parameter des HTTP-Aufrufs

Rückgabe-Werte

Fehler bei Angabe einer Rufnummer:

Prüfen Sie einfach ob in der zurückgegebenen Zeichenkette das Wort "ERROR" vorkommt, in diesem Fall wurde die SMS nicht versendet. Im Falle eines fehlerhaften Versands kann der zusätzliche Wert hinter dem Wort ErrorText: ausgewertet werden, dieser gibt den aufgetretenen Fehler an. z.B.

Return: ERROR
ErrorCode: 9999
ErrorText: Login fehlgeschlagen

Fehler bei Angabe mehrerer Rufnummern:

Prüfen Sie einfach ob in der zurückgegebenen Zeichenkette das Wort "ERROR" vorkommt, in diesem Fall wurden eine oder mehrere SMS nicht versendet. Im Falle eines fehlerhaften Versands kann der zusätzliche Wert hinter dem Wort ErrorText: ausgewertet werden, dieser gibt den aufgetretenen Fehler an. z.B.

Return: ERROR
ErrorCode: 9985
ErrorText: SMS-Text fehlt.
SMSSentCount: Anzahl der erfolgreich versendeten SMS bevor der Fehler auftrat
Nur während des eigentlichen Sendeversuchs:
LastTriedCellNo: Mobilfunknummer, bei welcher der Fehler auftrat, an diese Mobilfunknummer und die weiteren Nummern wurde keine SMS gesendet.

Wurde eine SMS versendet, wird OK zurückgegeben. Zusätzlich werden die Kosten der SMS zurückgegeben, z.B.

Return: OK
ErrorCode: 0
CustomerId: Kundennummer
SMSCosts: Kosten der SMS brutto (mit MwSt.),
SMSCostsWithOutVAT: Kosten der SMS netto (ohne MwSt.),
SMSSentCount: Anzahl der versendeten SMS, nur bei Angabe mehrerer Rufnummern
SentItemsId^*: interne ID der versendeten SMS, nur bei Einzel-SMS mit Antwort-Option verwendbar
SessionId: diese Angabe ist leer

^* Mit Hilfe der SentItemsId kann eine spätere Antwort auf die SMS zugeordnet werden, dazu muss im Kundenbereich unter "Pers.Daten" ein eigenes Script beim Eingang einer SMS und/oder Statusberichts angegeben werden.

Beispiel-URLs

Versand einer SMS ohne Absender an die Mobilfunknummer 01791234567 und SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567&SMSType=V1&SMSText=Das+ist+eine+Test+SMS

Versand mehrerer SMS ohne Absender an die Mobilfunknummern 01791234567 und 01791234568 mit dem SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567;01791234568&SMSType=V1&SMSText=Das+ist+eine+Test+SMS

Beispiel Versand einer SMS mit eigenem Absender an die Mobilfunknummer 01791234567 und SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567&SMSType=V3&SMSText=Das+ist+eine+Test+SMS

Beispiel Versand einer SMS mit eigenem Absender aber mit dem Absender-Text SMSout_SMS and die Mobilfunknummer 01791234567 und SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567&SMSType=V3&AltDisplayText=SMSout_SMS&SMSText=Das+ist+eine+Test+SMS

Einfaches Beispiel in Delphi 7 mit den Indy-Internet-Komponenten (Indy Komponenten)

// Funktion für URLEncode

// in neuere Delphi-Versionen ist ebenfalls möglich:
// uses System.NetEncoding, System.SysUtils; urlencoded := TNetEncoding.Url.Encode(<wert>, [], [], System.SysUtils.TEncoding.ANSI);
function UrlEncode(Src : String) : String;
var
I : Integer;
begin
Result := '';
For I := 1 to Length(Src) Do
begin
If Src[I] = '+' then
 Result := Result + '%' + IntToHex(ord(Src[I]), 2)
else
If Src[I] = ' ' then
 Result := Result + '+'
else
If Src[I] in ['a'..'z', 'A'..'Z', '0'..'9'] Then
 Result := Result + Src[I]
else
If (Ord(Src[I]) < 32) or (Ord(Src[I]) >= 127) Or (Src[I] in [':', '/', '\', '<', '>', '?', ';', '=', '&']) Then
 Result := Result + '%' + IntToHex(ord(Src[I]), 2)
else
 Result := Result + Src [I]
end;
end;

// SMSTyp darf nur 1, 2, 3, 4, 5, 6, 7 sein.
// SMSText maximal 160 Zeichen
// Indy HTTP Komponente wird für den SMS-Versand genutzt

// Für SMSTyp 6 und 7 muss der Aufruf mit HTTP.Post() ausgeführt werden

function SendSMS(const SMSoutAPIkey, SMSoutUsername, SMSoutPassword: String; const SMSTo: String; const SMSTyp: Integer; const SMSText: String): String;
Var
HTTP : TIdHTTP;
IdSSLIOHandler: TIdSSLIOHandlerSocketOpenSSL;
Data : String;

begin

   HTTP := TIdHTTP.Create(NIL);
  IdSSLIOHandler:= TIdSSLIOHandlerSocketOpenSSL.Create(HTTP); // for SSL connections, Owner is HTTP

   // für Aufruf mit https:// ist TLS v1.2 notwendig, die alten Indy Komponenten können nur TLS v1.2, nicht v1.3
  // ssleay32.dll und libeay32.dll müssen im Ordner der .exe-Ausgabedatei liegen, 32bit Version der DLLs, wenn die .exe 32bit ist, ansonsten die 64bit Varianten
  IdSSLIOHandler.SSLOptions.Method := sslvTLSv1_2;
  IdSSLIOHandler.SSLOptions.SSLVersions := [sslvTLSv1_2];

  HTTP.IOHandler := IdSSLIOHandler;
  HTTP.Request.UserAgent := 'SMSoutAPI'; // UserAgent unbedingt setzen, nicht den Standard-String Indy Library verwenden!!!!

   try

   // mit API key
   Data := Format('?APIkey=%s&SMSTo=%s&SMSType=V%d&SMSText=%s', [SMSoutAPIkey,
                              SMSTo, SMSTyp, UrlEncode(SMSText)] );

    { Alternative mit Benutzername und Passwort

     Data := Format('?Username=%s&Password=%s&SMSTo=%s&SMSType=V%d&SMSText=%s', [SMSoutUsername,
                             UrlEncode(SMSoutPassword), SMSTo, SMSTyp, UrlEncode(SMSText)] );
   }

    Result := HTTP.Get('https://www.smsout.de/client/sendsms.php' +  Data)
  finally

    HTTP.Free;
  end;
end;

// Testen

var
 S: String;

S := SendSMS('apikey aus smsout.de kundenbereich', 'username', 'password', '01791234567', 1, 'Das ist eine Test-SMS');

If Pos('ERROR', S) > 0 Then
  ShowMessage('SMS-Versand fehlgeschlagen, Fehler: ' + S)
else
  ShowMessage('Die SMS wurde versendet, Rückgabe: ' + S);

Beispiel in PHP 4/5/7/8

<?php

# Zugangsdaten
$APIkey = "apikey as smsout.de Kundenbereich";
$Username = "smsout-username";
$Password = urlencode("smsout-passwort");

# Zielrufnummer korrekt angeben!
$SMSTo = "01791234";

# Text der SMS, maximal 160 Zeichen
# beim Typ V6 bis zu 1560 Zeichen, wobei der Aufruf beim Typ 6 per HTTP Post erfolgen muss
# beim Typ V7 bis zu 1000 Zeichen, wobei der Aufruf beim Typ 7 per HTTP Post erfolgen muss
$SMSText = urlencode("Das ist eine Test SMS");

# SMS ohne eigenem Absender versenden, andere Werte V2, V3, V4, V5, V6 oder V7
$SMSType = "V1";

# Aufruf für den Versand der SMS
# Rückgabe ein Array mit dem Versandstatus
# für https://-Aufruf muss OpenSSL-Unterstützung im PHP aktiviert sein, in neueren PHP-Versionen fast immer der Fall

$result = file("https://www.smsout.de/client/sendsms.php?APIkey=$APIkey&SMSTo=$SMSTo&SMSType=$SMSType&SMSText=$SMSText");

/* Alternativ mit Übergabe Benutzername und Passwort
$result = file("https://www.smsout.de/client/sendsms.php?Username=$Username&Password=$Password&SMSTo=$SMSTo&SMSType=$SMSType&SMSText=$SMSText");
*/

if(is_array($result)) # falls es kein array ist, dann einfach so ausgeben
print join("<br>", $result);
else
print $result;

?>

Beispiel JAVA

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class SmsOutExample {

    public static void main(String[] args) {
        // Ihre Zugangsdaten und Parameter
        String apiKey = "IHR_API_KEY_HIER"; // Aus dem SMSout.de Kundenbereich
        String recipient = "491791234567";   // Zielrufnummer
        String smstype = "V3";              // SMS-Typ (z.B. V1, V2, V3 je nach Tarif/Absender)
        String text = "Hallo, das ist eine Test-SMS von SMSout.de!";

        try {
            // Text URL-kodieren (Umlaute, Leerzeichen etc.)
            String encodedText = URLEncoder.encode(text, StandardCharsets.UTF_8);

            // URL zusammenbauen
            String urlString = String.format(
                "https://www.smsout.de/client/sendsmsutf8.php", // sendsmsutf8.php verwenden, Text ist UTF-8 codiert
                apiKey, recipient, smstype, encodedText
            );

            // HTTP-Client erstellen
            HttpClient client = HttpClient.newHttpClient();
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(urlString))
                    .GET()
                    .build();

            // Anfrage absenden
            HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());

            // Ergebnis ausgeben
            System.out.println("HTTP-Statuscode: " + response.statusCode());
            System.out.println("Antwort vom Server: " + response.body());
            
            String s = response.body();

            if (s != null && s.contains("ERROR")) {
                System.out.println("SMS-Versand fehlgeschlagen, Fehler: " + s);
                // Wenn Sie eine grafische Oberfläche (Swing) nutzen, alternativ:
                // javax.swing.JOptionPane.showMessageDialog(null, "SMS-Versand fehlgeschlagen, Fehler: " + s);
            } else {
                System.out.println("Die SMS wurde versendet, Rückgabe: " + s);
            }


        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Guthaben und aktuelles SMS-Paket abfragen

Mit dem Aufruf

https://www.smsout.de/client/sendsms.php?APIkey=<smsout-api-key-aus-kundenbereich>&GetAccountData

oder

https://www.smsout.de/client/sendsms.php?Username=<smsout-username>&Password=<smsout-password>&GetAccountData

kann das Guthaben und das aktuelle SMS-Paket abgefragt werden.

Als Rückgabewert bei korrekter Angabe von API Key oder Benutzername/Passwort erhalten Sie diese Daten:

Return: OK
ErrorCode: 0
CustomerId: Kundennummer
AvailMoney: Verfügbares Guthaben mit MwSt.
AvailMoneyWithOutVAT: Verfügbares Guthaben ohne MwSt.
SMSPackageName: Aktuelles SMS-Paket
SessionId:

SMS mit UTF-8 codierten Zeichen

Anstatt des Scripts sendsms.php verwenden Sie das Script sendsmsutf8.php. Dieses Script wandelt alle UTF-8 codierten Zeichen vor dem SMS-Versand in iso-8859-1 codierte Zeichen um. Sind Zeichen nicht in iso-8859-1 umwandelbar, dann werden ? im SMS-Text enthalten sein.
Verwenden Sie das spezielle Script sendsmsutf8.php nur, wenn eine Umwandlung in iso-8859-1 nicht oder nur schwer möglich ist z.B. in JavaScript auf utf-8 codierten Webseiten oder in Smartphone Apps (SMSout App für Android).

SMSout und LinOTP

Als SMS Provider Konfiguration für LinOTP müssen diese Daten hinterlegt werden:

{"URL":"https://www.smsout.de/client/sendsmsutf8.php",
"PARAMETER": {
     "APIkey":"<api key aus SMSout.de Kundenbereich>",
     "SMSType":"V3"
  },
"SMS_TEXT_KEY":"SMSText",
"SMS_PHONENUMBER_KEY":"SMSTo",
"HTTP_Method":"GET",
"RETURN_SUCCESS":"Return: OK"
}

Alternativ mit Übergabe von Benutzername und Passwort (nicht empfohlen):

{"URL":"https://www.smsout.de/client/sendsmsutf8.php",
"PARAMETER": {
     "Username":"<smsout-username>",
     "Password":"<smsout-password>",
     "SMSType":"V3"
  },
"SMS_TEXT_KEY":"SMSText",
"SMS_PHONENUMBER_KEY":"SMSTo",
"HTTP_Method":"GET",
"RETURN_SUCCESS":"Return: OK"
}

Für <api key aus SMSout.de Kundenbereich> muss der API Key aus dem SMSout.de Kundenbereich hinterlegt werden. Beim Aufruf mit Benutzername und Passwort muss für <smsout-username> der SMSout.de-Nutzername und für <smsout-password> das SMSout.de-Passwort hinterlegt werden.
Die SMS wird mit Absender versendet (V3), dazu wird die Absender-Nummer oder hinterlegte Absender-Text aus dem SMSout.de-Kundenbereich verwendet.

Siehe auch

Mail2SMS-Schnittstelle

<< Zurück zu SMSout.de