Lertify Email2SMS omogoča pošiljanje SMS sporočil prek strukturiranega e-poštnega sporočila, ki ga uporabnik pošlje na svoj konfigurirani Email2SMS naslov. Sistem iz prejetega sporočila pridobi ključ API, podatke o pošiljatelju, prejemnike, vsebino SMS-a in morebitne dodatne nastavitve ter nato zahtevo posreduje v Lertify SMS sistem.

Pomembno: e-poštni naslov, s katerega je zahteva poslana, mora biti dovoljen za uporabljeni ključ API. Sam veljaven ključ API ne zadostuje, če pošiljateljev e-poštni naslov ni avtoriziran za ta račun.

Kako uporabljati Email2SMS

  1. Pošljite e-pošto – E-poštno sporočilo pošljite na naslov email2sms@lertify.app.

  2. Uporabite dovoljen e-poštni naslov – Če pri API ključu niso določeni dovoljeni e-poštni naslovi, lahko zahtevo privzeto pošljete s kateregakoli naslova. Če je določen eden ali več dovoljenih naslovov, bodo obdelane samo zahteve, poslane z njih.

  3. V telo e-pošte dodajte oznake – Zahteva mora vsebovati obvezne oznake
    #apikey#, #sender#, #startdestination# …
    #enddestination# in #startcontent# …
    #endcontent#.

  4. Dodajte prejemnike – Telefonske številke prejemnikov lahko ločite z novo vrstico, vejico ali podpičjem.

  5. Po želji dodajte dodatne nastavitve – Za dodatne možnosti lahko uporabite
    #defaultcc#, #isunicode#, #scheduledtime#,
    #pricereport# in #callbackurl#.

  6. Pošljite e-pošto – Če je zahteva pravilno sestavljena, se SMS odda v pošiljanje. V primeru napak pri obdelavi sistem pošlje povratno e-poštno sporočilo z informacijami o napaki.

Obvezna polja

Polje z oznako #apikey# mora imeti vrsto UUID. Uporablja se za identifikacijo računa in skupaj z naslovom From omogoča avtorizacijo zahteve.

Polje #sender# mora biti tipa string in je obvezno. V njem določite ime pošiljatelja ali telefonsko številko, ki jo lahko uporablja zadevni račun.

Razdelek med oznakama #startdestination# in #enddestination# je obvezen in ima vrsto section. V njem navedete eno ali več ciljnih telefonskih številk.

Razdelek med oznakama #startcontent# in #endcontent# je prav tako obvezen in je vrste section. Vsebuje besedilo SMS sporočila, ki bo poslano prejemnikom.

Izbirna polja

Oznaka #defaultcc# predstavlja privzeto klicno številko države za lokalne telefonske številke. Gre za vrednost tipa string, privzeta vrednost pa je 386.

Z oznako #isunicode# določite, ali naj se vsebina sporočila obravnava kot Unicode. Polje je tipa boolean in lahko vsebuje vrednost true ali false. Privzeto je nastavljeno na false.

Polje #scheduledtime# omogoča določitev časa načrtovanega pošiljanja. Gre za vrednost tipa long, ki predstavlja Unix časovni žig v sekundah, na primer 1789290000.

Z oznako #pricereport# lahko zahtevate vključitev cene v poročilo o dostavi, kadar je ta podatek na voljo. Polje je tipa boolean in privzeto vsebuje vrednost false.

Polje #callbackurl# je tipa string in določa URL, na katerega se pošiljajo poročila o dostavi SMS sporočil.

Minimalni primer e-pošte

#apikey#
12345678-1234-1234-1234-123456789abc

#sender#
Lertify

#startdestination#
040123456
#enddestination#

#startcontent#
Testno SMS sporočilo
#endcontent#

V navedenem primeru se številka 040123456 glede na privzeto državo 386 pretvori v obliko +38640123456.

Če vrednost #apikey# ni v pravilni obliki, se e-poštno sporočilo
zavrne in se ne obdela.

Pri drugih napakah se e-poštno sporočilo sprejme. Zaznane napake se uporabniku
posredujejo po e-pošti, kot je opisano v obstoječi dokumentaciji.

Celoten primer e-pošte

#apikey#
12345678-1234-1234-1234-123456789abc

#sender#
Lertify

#defaultcc#
386

#isunicode#
false

#scheduledtime#
1789290000

#pricereport#
False

#callbackurl#
https://example.com/delivery-report

#startdestination#
+38640123456
0038640987654
031555111; 041222333
#enddestination#

#startcontent#
Testno SMS sporočilo poslano prek Email2SMS.
#endcontent#

Pravila za telefonske številke

Preden Email2SMS zahtevo posreduje v obdelavo, normalizira telefonske številke prejemnikov glede na vrednost #defaultcc#. Pri tem se uporabljajo naslednja pravila:

  • Številka, ki se začne z +, ostane nespremenjena.
  • Pri številki, ki se začne z 00, se začetni 00 nadomesti z znakom +.
  • Če se številka začne z 0, se začetna ničla odstrani, nato pa se doda privzeta klicna številka države.
  • Če številka nima nobene od navedenih predpon, se pred njo doda privzeta klicna številka države.
  • Če je ista telefonska številka navedena večkrat, se podvojeni vnosi odstranijo.

#defaultcc#
386
040123456 -> +38640123456
0038640123456 -> +38640123456
+38640123456 -> +38640123456

Po izvedeni normalizaciji za telefonske številke veljajo še pravila SMS sistema. Ciljne številke morajo biti veljavne in podprte za pošiljanje. Če je številka neveljavna ali ni podprta, lahko sistem zahtevo zavrne.

Več prejemnikov

Pri vnosu več prejemnikov lahko telefonske številke med seboj ločite z novo vrstico, vejico ali podpičjem. 

#startdestination#
040123456
040987654,031555111;+385911234567
#enddestination#

Načrtovano pošiljanje

Z oznako #scheduledtime# določite čas, ob katerem naj bo SMS sporočilo načrtovano za pošiljanje. Vrednost mora biti podana kot Unix časovni žig v sekundah. 

#scheduledtime#
1789290000

Če oznaka #scheduledtime# v e-pošti ni navedena, se sporočilo pošlje takoj po uspešni obdelavi zahteve.

Če podana vrednost ni veljavno celo število oziroma ne predstavlja veljavnega Unix časovnega žiga v sekundah, zahteva za načrtovano pošiljanje ni veljavna.

Unicode in dolžina sporočila

Oznaka #isunicode# določa način obdelave vsebine SMS sporočila. Pri vrednosti false se vsebina, kadar je to mogoče, obravnava v skladu s pravili GSM. Če je vrednost true, se vsebina ohrani in obdela kot Unicode.

Po obdelavi vsebine je dovoljeno največ 640 znakov.

Poročila o dostavi in cena

URL za prejemanje poročil o dostavi določite z oznako #callbackurl#. Če želite, da poročilo vsebuje tudi ceno, kadar je ta na voljo, nastavite #pricereport# na true. Za poročila veljajo enaka pravila kot pri Lertify SMS API. 

#pricereport#
true
#callbackurl#
https://example.com/delivery-report

Avtentikacija in varnost

Email2SMS pri obdelavi zahteve preverja tako ključ API kot e-poštni naslov, s katerega je bilo sporočilo poslano.

  • Vrednost oznake #apikey# mora biti veljaven UUID.
  • Če za uporabljeni ključ API ni nastavljen noben dovoljen e-poštni naslov, je mogoče zahtevo poslati s kateregakoli e-poštnega naslova.
  • Če je za ključ API določen eden ali več dovoljenih e-poštnih naslovov, mora biti zahteva poslana z enega od njih.
  • Če uporabljeni e-poštni naslov ni avtoriziran za ključ API, SMS sporočilo ne bo poslano.

Priporočilo: ključ API obravnavajte kot skrivni podatek in Email2SMS uporabljajte samo z dovoljenih e-poštnih naslovov. Ključa API ne razkrivajte tretjim osebam.

Obdelava napak

Če je telo e-pošte prazno, se sporočilo obravnava kot že obdelano, vendar se SMS ne pošlje.

Če manjka oznaka #apikey# ali podani ključ ni veljaven UUID, se e-pošta prav tako označi kot obdelana, SMS pa ni poslan.

Če naslov From ni avtoriziran za uporabljeni API ključ, se e-poštna zahteva zavrne in SMS ni poslan.

Če v zahtevi manjka oznaka #sender#, pošiljatelj prejme e-poštno sporočilo z opisom napake.

Enako velja, če razdelek destination manjka ali ne vsebuje nobenega prejemnika. V tem primeru sistem pošlje pošiljatelju obvestilo o napaki.

Če manjka razdelek content, bo pošiljatelj prav tako prejel e-pošto z napako.

Če validacija SMS sistema zahtevo zavrne, se pošiljatelju pošlje e-poštno sporočilo z opisom ugotovljene napake.

Pri začasni sistemski ali HTTP napaki oziroma pri časovni prekoračitvi (timeout) e-pošta ne bo označena kot obdelana. Tako jo je mogoče ponovno poskusiti obdelati.

Naslov povratnega sporočila, ki se uporablja pri validacijski napaki, je:
Lertify Email2SMS – Error

Sintaksa oznak

Oznake razlikujejo velike in male črke, zato jih je treba zapisati natančno tako, kot so navedene v dokumentaciji. Uporabljajte jih z malimi črkami.

Pri oznakah, ki predstavljajo enovrstično vrednost, sistem prebere vrednost iz naslednje vrstice za posamezno oznako. 

#sender#
Lertify01

#isunicode#
false

Pri večvrstičnih razdelkih se obdela celotno besedilo, ki se nahaja med začetno in končno oznako. 

#startcontent#
Besedilo sporočila je lahko
zapisano v več vrsticah.
#endcontent#

Enako pravilo velja za razdelek, v katerem so navedeni prejemniki: 

#startdestination#
+38640123456
+38640987654
#enddestination#

Za pravilno obdelavo večvrstičnega razdelka morata biti vedno prisotni tako začetna kot tudi končna oznaka.