2013/11: gemilot webové služby

GUC: Webove služ by

Specifikace rozhraní webových služeb aplikace GUC

Zpracoval: Lukáš Hakoš Kontroloval: Václav Pelc, Jan Jurko, Tomáš Šůstek Verze: 1.0.1.1 Ze dne: 03. 04. 2014

Verze 1.0.1.1 ze dne 03. 04. 2014 2 / 38

Copyright © Gemilot s.r.o., 2013–2014. Všechny práva vyhrazena.

Obsah tohoto dokumentu podléhá autorskému právu. Používání, jakož i změny, zkrácení, rozšiřování

a doplňování vyžaduje předchozí písemný souhlas společnosti Gemilot s.r.o. Jakékoliv rozmnožování

je povoleno pouze za podmínky, že na rozmnoženém dokumentu zůstane zachováno označení

původu. Každé rozmnožování nebo překlad si vyžaduje předchozí písemné povolení Gemilot s.r.o.

Verze 1.0.1.1 ze dne 03. 04. 2014 3 / 38

1 Obsah 2 Tabulky ............................................................................................................................................ 4

3 Obrázky ............................................................................................................................................ 5

Historie změn .......................................................................................................................................... 6

4 Úvod ................................................................................................................................................ 7

4.1 Účel dokumentu ...................................................................................................................... 7

5 Architektura GUC............................................................................................................................. 8

6 Webové služby ................................................................................................................................ 9

6.1 Současný běh více rozhraní ..................................................................................................... 9

7 Definice SOAP zpráv ...................................................................................................................... 11

7.1 Poruchové zprávy .................................................................................................................. 11

7.1.1 Zpracování aplikačních výjimek ..................................................................................... 11

7.2 Používané jmenné prostory................................................................................................... 11

7.3 Zabezpečení – autentizace a autorizace................................................................................ 11

7.3.1 Přihlašovací údaje k webovým službám ........................................................................ 12

8 Režim pískoviště ............................................................................................................................ 13

8.1.1 Přihlašování do pískoviště ............................................................................................. 13

9 Rozhraní: Global Services .............................................................................................................. 14

9.1 Věcný obsah .......................................................................................................................... 14

9.2 Metoda: getVersion() ............................................................................................................ 14

9.2.1 Popis .............................................................................................................................. 14

9.2.2 Rozhraní ......................................................................................................................... 14

9.2.3 Příklady komunikace formou SOAP zpráv ..................................................................... 14

9.3 Metoda: getVersionWithCredentials() .................................................................................. 15

9.3.1 Popis .............................................................................................................................. 15

9.3.2 Rozhraní ......................................................................................................................... 15

9.3.3 Příklady komunikace formou SOAP zpráv ..................................................................... 15

10 Rozhraní: Import / Export .......................................................................................................... 16

10.1 Věcný obsah .......................................................................................................................... 16

10.2 Metoda: ImportSingleEmailContact().................................................................................... 16

10.3 Metoda: EmailList() ............................................................................................................... 17

10.4 Metoda: FullContactList() ...................................................................................................... 19

10.5 Metoda: ChangeEmailStatus() ............................................................................................... 21

Verze 1.0.1.1 ze dne 03. 04. 2014 4 / 38

11 Rozhraní: E-mail Campaign ........................................................................................................ 23

11.1 Věcný obsah .......................................................................................................................... 23

11.2 Metoda: getOutgoingEmails() ............................................................................................... 23

11.3 Metoda: setUploadAttachment() .......................................................................................... 24

11.4 Metoda: getListOfAttachments() .......................................................................................... 26

11.5 Metoda: getDownloadAttachment() ..................................................................................... 27

11.6 Metoda: sendMailByString() ................................................................................................. 28

11.7 Metoda: simpleSendSingleMail() .......................................................................................... 31

11.8 Metoda: getVerificationSingleEmailAddress() ...................................................................... 33

11.9 Metoda: getVerificationListOfEmailAddress() ....................................................................... 35

12 Seznam použitých číselníků ....................................................................................................... 36

12.1 Autentifikace ......................................................................................................................... 36

12.2 I/O stavy ................................................................................................................................ 36

12.3 Zakázané extenze souborů .................................................................................................... 37

2 Tabulky Tabulka 1: Umístění jednotlivých rozhraní webových služeb ................................................................. 9

Tabulka 2: Využívané jmenné prostory ................................................................................................. 11

Tabulka 3: Vstupní parametry webové metody .................................................................................... 14



Tabulka 6: Výstupní data metody .......................................................................................................... 16


















Verze 1.0.1.1 ze dne 03. 04. 2014 5 / 38


Tabulka 15: Vstupní parametry webové metody .................................................................................. 34

Tabulka 16: Výstupní data metody ........................................................................................................ 34

Tabulka 17: Vstupní parametry webové metody .................................................................................. 35

Tabulka 18: Výstupní data metody ........................................................................................................ 35

3 Obrázky Obrázek 1: Propojení služeb a vnější okolí .............................................................................................. 7

Obrázek 2: Schéma aplikace bez poštovní složky .................................................................................... 8

Verze 1.0.1.1 ze dne 03. 04. 2014 6 / 38

Historie změn Verze 1.0.1.1 (03. 04. 2014)

(1) Oprava odkazu na platební bránu.

Verze 1.0.1.0 (23. 03. 2014)

(1) Aktualizace data dokumentu.

Verze 1.0.0.0 (10. 01. 2013)

(1) Vytvoření prvotní dokumentace k WS GUC.

Verze 1.0.1.1 ze dne 03. 04. 2014 7 / 38

4 Úvod Tento dokument popisuje vnější rozhraní webových služeb, které aplikace Gemilot Unified

Communications (dále jen „GUC“) nabízí svým klientům jako doplněk standardní webové grafické

aplikace. Dokument je zpracován v rámci projektu „Automatizované komunikace“ na úrovni

specifikace příslušných rozhraní používaných mezi subjekty.

Specifikace popisovaných webových služeb byla vytvořena ve spolupráci Gemilot s.r.o. (dále jen

„Gemilot“) a několika významných klientů z řad korporátní sféry. Dokumentace je určena

pracovníkům, kteří jsou odpovědni za přípravu a provoz dané části informačních systémů napojených

na GUC v rámci externího partnera.

4.1 Účel dokumentu Účelem dokumentu je specifikace webových služeb, které umožňují zadávat požadavky na aplikaci

GUC automatizovaným procesem formou komunikace přes webové služby.

Skupina popisovaných webových služeb se týká částí práce s e-maily a odběrateli, zpětným

reportingem a sadou obecných metod pro ověření a testování provozu vzájemné interoperability.

Specifikace obsahuje popis formátu předávaných zpráv, formátů jednotlivých položek a popis

logických podmínek pro jejich věcný obsah. V dokumentu jsou specifikovány webové služby pro

oblasti:

E-mailové služby (EmailCampaign.asmx)

Importní a exportní služby (ImportExport.asmx)

Globální služby (GlobalServices.asmx)

Vzájemné propojení webových služeb se systémem GUC, a jejími subsystémy, je uvedeno na obrázku

níže.

Obrázek 1: Propojení služeb a vnější okolí

Verze 1.0.1.1 ze dne 03. 04. 2014 8 / 38

5 Architektura GUC Pro možnost korektní komunikace s webovými službami GUC a pochopení funkcionality tohoto

systému je bezpodmínečně nutné vědět, jak aplikace funguje – z čeho se skládá, co jsou její aktivní a

pasivní prvky. Jedině tak je potom možné optimalizovat dotazy na služby, aby byly skutečně efektivní,

zejména co do výkonu provádění požadavků.

Aplikace GUC se skládá z několika subsystémů a podpůrných prvků:

Webové servery (WS, grafická část GUC)

Databáze (uživatelská data)

Souborový systém (data kampaní)

Aplikační servery (poštovní servery, jiné podpůrné služby)

Další složky (síťové prvky a služby, zabezpečení, dohled…)

Běžný uživatel přichází do styku s aplikací GUC zpravidla přes její webové rozhraní nalézající se na

adrese https://guc.gemilot.com. Tam může uživatel provádět běžné činnosti a operace, které

postačují 95 % všech uživatelů, jako je tvorba kampaní, správa odběratelů, správa vlastního účtu aj.

Paralelně k výše zmíněné aplikaci běží ještě dvě webové aplikace – platební brána

(http://billing.gemilot.com), kde klient může spravovat finanční stránku svého účtu, pokud nemá

nastaven účet typu „Free“; a webové služby (https://ws.gemilot.com), kde může klient komunikovat

s aplikací pomocí automatizovaného rozhraní formou SOAP1 zpráv. Toto rozhraní je výhodné, pokud

klient spravuje svá data ze svého systému a chce mít svůj systém propojen napřímo s GUC tak, aby

měl vysoký uživatelský komfort.

Tím veřejné součásti rozhraní končí.

Obrázek 2: Schéma aplikace bez poštovní složky

1 Simple Object Access Protocol; URL: http://en.wikipedia.org/wiki/SOAP

https://guc.gemilot.com/

http://billing.gemilot.com/

https://ws.gemilot.com/

Verze 1.0.1.1 ze dne 03. 04. 2014 9 / 38

6 Webové služby Prostřednictvím webových služeb nabízí aplikace GUC funkcionalitu, která umožňuje klientovi

komunikovat a spolupracovat v reálném čase s webovou a aplikační částí rozhraní pomocí

automatizovaných příkazů a procesů, dle předem domluvených pravidel, které jsou popsány v tomto

dokumentu. Webové služby nabízí tuto funkcionalitu:

Global Services

o Informace o verzi webových služeb, včetně data nasazení <getVersion()>

o Informace o verzi webových služeb, včetně data nasazení s použitím přihlašovacích

údajů <getVersionWithCredentials()>

Import / Export Service

o Změna stavu e-mailové adresy <ChangeEmailStatus()>

o Výpis e-mailových adres dle filtru <EmailList()>

o Výpis úplného objektu kontaktu klienta <FullContactList()>

o Import nového e-mailu mezi odběratele klienta <ImportSingleEmailContact ()>

E-mail Campaign

o Výpis e-mailových adres pro odchozí kampaně <getOutgoingEmails()>

o Nahrání přílohy pro kampaně <setUploadAttachment()>

o Výpis uložených příloh pro kampaně <getListOfAttachments()>

o Stažení vybrané přílohy pro kampaně <getDownloadAttachment()>

o Odeslání komplexní kampaně <sendMailByString()>

o Primitivní odeslání kampaně <simpleSendSingleMail()>

o Ověření jedné e-mailové adresy <getVerificationSingleEmailAddress()>

o Ověření listu e-mailových adres <getVerificationListOfEmailAddress()>

Výše uvedené webové služby jsou dostupné na adrese https://ws.gemilot.com, kde komunikace

probíhá přes šifrovaný protokol HTTPS2.

6.1 Současný běh více rozhraní Protokol webové služby se může v průběhu času měnit. Pro zajištění hladkého přechodu mezi

verzemi protokolu je klientům umožněna paralelní komunikace jak s novou verzí rozhraní, tak i s verzí

předchozí. Tato možnost dává klientům čas na přizpůsobení svých klientských aplikací. Avšak je vždy

pouze dočasná.

Verzování protokolů webových služeb odpovídá roku a měsíci, ve kterém protokol byl prvně

publikován jako stabilní verze. Verze protokolu se pak pro jasnější odlišení objevuje jak ve jmenném

prostoru věcných elementů v obsahu SOAP zpráv, tak v URL adrese přístupového bodu.

Tabulka 1: Umístění jednotlivých rozhraní webových služeb

Verze protokolu Adresa rozhraní Adresa WSDL

2013/11 /2013/11/GlobalServices.asmx /2013/11/GlobalServices.asmx?WSDL 2013/11 /2013/11/EmailCampaign.asmx /2013/11/EmailCampaign.asmx?WSDL 2013/11 /2013/11/ImportExport.asmx /2013/11/ImportExport.asmx?WSDL

2 Ve skutečnosti je dostupná i verze bez SSL. To proto, že některé systémy mohou trpět chybami v komunikaci v šifrované komunikaci (např. problematika certifikátů, CA aj.). Pokud to ale jen trochu jde, výrazně doporučujeme komunikaci přes HTTPS.

https://ws.gemilot.com/

Verze 1.0.1.1 ze dne 03. 04. 2014 10 / 38

Verze 1.0.1.1 ze dne 03. 04. 2014 11 / 38

7 Definice SOAP zpráv Webové služby systému GUC používají dva protokoly komunikace – SOAP v1.1 a SOAP v1.2. To

z důvodu maximální adaptability systémů na klientské řešení. Metody GET a POST jsou užity pouze

v omezené míře záměrně z důvodu bezpečnosti.

7.1 Poruchové zprávy Poruchové zprávy jsou odeslány v případě, že bude navázána chybová komunikace se serverem, který

realizuje popisované webové služby. Struktura elementu <Fault> odpovídá standardní definici z

prostoru SOAP v1.1 a SOAP v1.2.

Chybová komunikace může být několika typů:

1. Interní chyba komunikace

a. Vznik na straně našeho aplikačního serveru, nebo vně služby při zpracovávání

požadavku.

2. Externí chyba komunikace

a. Klient zasílá chybná data na webovou službu, která neodpovídají definicím a popisu

uvedeným v tomto dokumentu.

7.1.1 Zpracování aplikačních výjimek

Všechny vzniklé aplikační výjimky, které ať již způsobí náš systém sám, nebo na základě

(ne)korektního volání ze strany klienta, plně zaznamenáváme do seznamu všech aplikačních

incidentů. Tento seznam nám slouží pro okamžitou identifikaci vzniklých chyb a současně pro jejich

následnou opravu.

Je na uživateli, zda nám bude vzniklé chyby reportovat, nebo to plně ponechá v naší režii.

V seznamu nově vydané verze webových služeb je vždy uveden seznam, co daná verze řeší, včetně

těchto vzniklých chyb.

7.2 Používané jmenné prostory Ve všech zprávách jsou používány jmenné prostory, které mají přiřazen specifikovaný význam.

Současně s těmito prostory je standardně používán i jejich stejný prefix.

Tabulka 2: Využívané jmenné prostory

Prefix Jmenný prostor Význam

soap: http://www.w3.org/2003/05/soap-envelope Definice obálky SOAP protokolu v1.2 soapenv: http://schemas.xmlsoap.org/soap/envelope/ Definice obálky SOAP protokolu v1.1 ws: https://ws.gemilot.com/ Globální definice obálky zprávy

7.3 Zabezpečení – autentizace a autorizace Všechny naše webové služby, které komunikují přímo se systémem GUC, je potřeba zajistit vysokou

mírou bezpečnosti. Krom běhu na vrstvě SSL, jako všechny ostatní služby, je potřeba před zahájením

každé komunikace s webovou službou se této službě ověřit platným uživatelským jménem a heslem3,

kterým pro účely přístupu k webovým službám říkáme GUID a Token.

3 Tato teze neplatí úplně pro webovou službu „Global Services“.

Verze 1.0.1.1 ze dne 03. 04. 2014 12 / 38

Tato uživatelská přístupová data si můžete nechat vygenerovat v Administračním panelu GUC.

Přístup k této volbě má uživatel s právy Administrátor účtu a Import.

INFO

Při přihlašování k metodám webových služeb nepoužívejte vlastní přihlašovací údaje, které používáte do webové aplikace. Tyto přihlašovací údaje pro rozhraní webových služeb neplatí a je potřeba o ně zažádat v Administračním panelu GUC.

Autentizace – pro přístup k webové službě je potřeba mít uživatelské jméno a heslo, viz výše. Pomocí

této dvojice údajů můžete klást požadavky na webovou službu. Tuto sadu údajů je potřeba zadávat

při jakémkoliv dotazu. Není umožněno zadat tyto údaje pouze jednou, aby byly platné po celou dobu

sezení.

Autorizace – systém GUC na základě zadaných autentizačních údajů kontroluje oprávnění daného

uživatelského účtu pro přístup k webovým službám. Pokud uživatel má právo pracovat s tímto

rozhraním, je mu povolen přístup k potřebným akcím. V opačném případě končí sezení chybou

s nemožností o ověření uživatele.

Samotný přístup k webové službě, jejím WSDL, XSD apod. je volně přístupný. To proto, aby se snadno

dal tento obsah zpracovat. Přístup ale k samotným metodám, co by do vykonání instrukcí, je již

zabezpečen pomocí SOAP hlavičky4. Tento formát přihlášení je zvolen z důvodu podpory všech

systémů a snadné implementace ve vlastním řešení.

7.3.1 Přihlašovací údaje k webovým službám

Pro přístup k webovým službám, tj. získání unikátních identifikátorů GUID a Token, je potřeba si tuto

službu předplatit v Platební bráně GUC s možností výběru platnosti od–do.

Přístup k těmto službám je pevně spjat s uživatelským finančním účtem a bez něj není možno dané

služby využívat.

4 SOAP Header obsahuje dvě pole: <GUID> a <Token>, kterými se ověřuje platnost přístupu k dané webové metodě.

Verze 1.0.1.1 ze dne 03. 04. 2014 13 / 38

8 Režim pískoviště Režim pískoviště byl do aplikace webových služeb GUC zaveden z toho důvodu, aby vývojáři

klientských aplikací (aplikací třetích stran) měli možnost testovat své nástroje na nezávislém zdroji

dat bez obavy, že budou na ně aplikovány nějaké zvláštní poplatky.

Tento režim proto slouží výhradně pro testování vlastních aplikací, ať již při jejich vývoji nebo

ověřování funkcionality a není určen pro hromadné vytěžování a zpracování dat.

Vzhledem k tomu, že tento režim je pouze pro „hrátky“ s naším systémem v rámci ověření vlastních

funkcionalit, vztahují se na toto prostředí zvláštní pravidla:

Pravidlo přístupu: Tento režim je přístupný každému klientovi, který má zakoupené a platné webové

služby v rámci jeho klientského účtu. Přístup do tohoto prostředí, po úspěšném potvrzení platby,

může být nicméně se zpožděním a to díky synchronizaci dat mezi produkčním a testovacím během

aplikace. Toto zpoždění by nemělo být delší než 30 (třicet) minut. Pravidlo poskytnutí rozhraní: Toto

rozhraní je vždy identické 1:1 s rozhraním produkčním.

Pravidlo dostupnosti služby: Tato služba je poskytována „tak, jak je“ bez záruky 100% dostupnosti.

Naším cílem je zejména držet v chodu provoz produkčního prostředí. O plánovaných odstavcích

systému dáváme klientům dopředu vědět, zpravidla 7 (sedm) kalendářních dní, aby se na to mohli

připravit.

Pravidlo zachování dat: Jelikož i testovací data mohou ve výsledku klást velké nároky na diskovou

infrastrukturu a kapacitu, vyhraňujeme si možnost testovací prostředí kdykoliv promazat a to bez

nároku na refundaci za ztrátu dat v rámci testovacího provozu. Cyklus promazávání je nastaven na 1x

za měsíc, nicméně může nastat častěji, pokud budeme potřebovat. O této skutečnosti dáváme

klientům dopředu vědět.

Pravidlo práce s daty: Vše, co si budete stavět na pískovišti je jen Vaše Nicméně je potřeba myslet

na ten fakt, že vše, co umístíte k odeslání, odesláno být nemusí (ale zpravidla bude ). Ne, že

bychom byli zlí a nechtěli Vám dopřát té krásy podívat se na Vaše výtvory, ale prioritou je hlavně

hladký a bezproblémový chod produkce.

8.1.1 Přihlašování do pískoviště

Přihlašování do režimu pískoviště je naprosto totožné s přihlašováním se do produkční verze

webových služeb. Tj. identifikátory GUID a Token jsou mezi těmito dvěma prostředími plně sdíleny.

Při objednání této služby pro produkční prostředí je možnost práce s webovými službami okamžitá.

Pro režim pískoviště pouze platí, že se daná prostředí musí synchronizovat (produkce a test). Z toho

důvodu je možné, že se do testovacího prostředí půjde přihlásit nejdéle za 30 minut od zaplacení

přístup v Platební bráně GUC.

Posledním rozdílem rovněž je, že všichni uživatelé testovacího prostředí tam mají nastaven jako

klientský účet – typ FREE.

Verze 1.0.1.1 ze dne 03. 04. 2014 14 / 38

9 Rozhraní: Global Services

9.1 Věcný obsah Webová služba Global Services poskytuje pouze globální informace o systému bez další přidané

hodnoty a logiky. Slouží zejména pro ověření napojení na naše služby, což nejvíce ocení vývojáři,

zjištění aktuální používané verze webových služeb jako celku a informace o datu nasazení balíku

služeb do produkčního prostředí, tzv. Deployment.

Do budoucna se plánuje pouze omezený rozvoj tohoto rozhraní, a to především proto, že tato služba

má být spíše informativního charakteru, než charakteru výkonového.

9.2 Metoda: getVersion()

9.2.1 Popis

Tento vnější interface slouží pro zjištění identifikace verze aktuálně využívaných webových služeb

jako celku a informace o datu nasazení této verze do produkčního prostředí webového serveru.

Webové služby vždy nasazujeme jako jeden celistvý celek. To z toho důvodu, že jejich provázanost a

napojení na další subsystémy aplikace GUC nedovoluje publikování tohoto rozhraní jinak. Jelikož

všechny webové služby – jakož i aplikační servery na pozadí – běží v clusterovém prostředí a navíc v

několika geolokacích, nasazují se aktualizace na tzv. master servery, které se postarají o replikaci

aplikací a aplikačních částí do ostatních strojů.

Smyslem uveřejnění čísla verze aktuálně použitých webových služeb je zejména řešení chybových

situací (aplikačních výjimek). Pokud klient komunikuje s našimi službami a má pocit, že mu služby

neodpovídají korektně, tak, jak by měly, je identifikace verze služby klíčovou informací, jelikož služby

se mohou i po čas vývojového cyklu software několikrát v krátkém čase změnit.

9.2.2 Rozhraní Tabulka 3: Vstupní parametry webové metody

Parametr Povinný Definiční obor Poznámka

– – – –

9.2.3 Příklady komunikace formou SOAP zpráv

SOAP požadavek

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:glob="https://ws.gemilot.com/GlobalService">

<soap:Header/>

<soap:Body>

<glob:getVersion/>

</soap:Body>

</soap:Envelope>

SOAP odpověď


xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<getVersionResponse xmlns="https://ws.gemilot.com/GlobalService">

<getVersion xmlns="https://ws.gemilot.com/IGlobalServices/getVersion">

Verze 1.0.1.1 ze dne 03. 04. 2014 15 / 38

<Version>1.0.504.14068</Version>

<DeploymentDate>2014-03-09</DeploymentDate>

</getVersion>

</getVersionResponse>

</soap:Body>

</soap:Envelope>

9.3 Metoda: getVersionWithCredentials()

9.3.1 Popis

Webová metoda je v interní části na pozadí totožná s metodou getVersion(), která je popisována

výše. Rozdílem této metody proti výše zmíněné je pouze ten fakt, že zde vstupuje do role i ověřovací

vrstva pro připojení k webové službě.

Toho se dá využít k ověření korektního zasílání SOAP ověřovací hlavičky webové metodě, která,

pokud je vše provede korektně, vrací stav úspěšného přihlášení.

9.3.2 Rozhraní Tabulka 4: Vstupní parametry webové metody


– – – –

9.3.3 Příklady komunikace formou SOAP zpráv

SOAP požadavek


xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"

xmlns:glob="https://ws.gemilot.com/GlobalService">

<soap:Header>

<user:UserHeader>

<user:GUID>3ed663f7-5897-4a7a-aec8-f99faddf9eb0</user:GUID>

<user:Token>sHrFXfAhLt0@5YyrZ$XtymB!K!YCzO3F</user:Token>

</user:UserHeader>

</soap:Header>

<soap:Body>

<glob:getVersionWithCredentials/>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<getVersionWithCredentialsResponse

xmlns="https://ws.gemilot.com/GlobalService">

<getVersionWithCredentials

xmlns="https://ws.gemilot.com/IGlobalServices/getVersionWithCredentials">

<LoginStatus>200</LoginStatus>

<Version>1.0.504.14068</Version>

<DeploymentDate>2014-03-09</DeploymentDate>

</getVersionWithCredentials>

</getVersionWithCredentialsResponse>

</soap:Body>

</soap:Envelope>

Verze 1.0.1.1 ze dne 03. 04. 2014 16 / 38

10 Rozhraní: Import / Export

10.1 Věcný obsah Webová služba Import / Export slouží pro import dat z externích systémů klienta do aplikace GUC

přes unifikované rozhraní, které spojuje všechny entity systémů – tj. centralizuje správu kontaktů

napříč celým řešením aplikace GUC. Současně, v paralelní dostupnosti, umožňuje i získávat již uložená

data ze systému GUC zpět do klientského systému.

Služba zajišťuje především tuto činnost:

Import nové e-mailové adresy;

Výpis uložených e-mailových adres na základě vstupního filtru;

Změna stavu platnosti e-mailové adresy;

Zobrazení úplného objektu kontaktu klienta.

Rozvoj této služby se předpokládá kontinuální, dle potřeb klientů a rozvoje systému GUC.

10.2 Metoda: ImportSingleEmailContact() Tato metoda zajišťuje import výhradně nových kontaktů pod profil aktuálně přihlášeného klienta.

Metoda podporuje import současně pouze jedné e-mailové adresy.

Při samotném importu nových dat vždy dochází ke kontrole, zda již jednou tento – a ten samý – e-

mail není přítomen pod profilem klienta. Pokud není, proběhne import nového záznamu. Pokud již je,

služba import neprovede a dá tuto skutečnost vědět klientovi.

Tabulka 5: Vstupní parametry webové metody


EmailAddress Y String E-mailová adresa nového kontaktu

Tabulka 6: Výstupní data metody

Parametr Definiční obor Poznámka

LoginStatus Int16 Stav přihlášení (viz část 12.1). ImportStatus Int16 Stav importu e-mailové adresy pod klientský účet

(viz část 12.2). EmailID UInt32 Unikátní ID e-mailové adresy v rámci systému GUC.

Lze užít pro budoucí korelaci záznamu.

ImportedEmail String Opis importované e-mailové adresy.

10.2.1.1 Příklady komunikace formou SOAP zpráv

SOAP požadavek



xmlns:imp="https://ws.gemilot.com/ImportExport">

Verze 1.0.1.1 ze dne 03. 04. 2014 17 / 38

<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<imp:ImportSingleEmailContact>

<imp:EmailAddress>[email protected]</imp:EmailAddress>

</imp:ImportSingleEmailContact>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<ImportSingleEmailContactResponse

xmlns="https://ws.gemilot.com/ImportExport">

<ImportSingleEmailContact

xmlns="https://ws.gemilot.com/ImportExport/ImportSingleEmailContact">


<ImportStatus>203</ImportStatus>

<EmailID>119842</EmailID>

<ImportedEmail>[email protected]</ImportedEmail>

</ImportSingleEmailContact>

</ImportSingleEmailContactResponse>

</soap:Body>

</soap:Envelope>

10.3 Metoda: EmailList() Tato metoda slouží pro úplný výpis e-mailových adres, z pohledu – co by do odběratelů –, klienta.

Metoda poskytuje klientovi komplexní odpověď formou vždy úplných dat, které jsou k okamžiku

dotazu právě platné v systému GUC.



typeOfRecord Y Enum(Active, Inactive, Active_Inactive, Deleted)

Typ výstupu, který chceme získat. Možnosti:

Active: Aktivní a platné e-mailové adresy.

Inactive: Neaktivní e-mailové adresy, které nejsou využívány pro kampaně.

Active_Inactive: Kombinace výše uvedených dohromady.

Deleted: E-mailové adresy, které jsou označeny ke smazání ze strany uživatelů v rámci opt-out principu.



LoginStatus Int16 Stav přihlášení (viz část 12.1).

Verze 1.0.1.1 ze dne 03. 04. 2014 18 / 38

ListOfEmails:<EmailAddress> String Vlastní hodnota e-mailové adresy ListOfEmails:<Email_ID> String Unikátní ID e-mailové adresy v rámci systému

GUC. ListOfEmails:<Contact_ID> String Unikátní ID objektu kontaktu, ke kterému je daná

e-mailová adresa přiřazena. ListOfEmails:<Status> Enum(Active,

Inactive, Deleted)

Enumerační výčet informace, v jakém stavu se data nacházejí. Možné hodnoty: • Active: Aktivní a platné e-mailové adresy. • Inactive: Neaktivní e-mailové adresy, které nejsou využívány pro kampaně. • Deleted: E-mailové adresy, které jsou označeny ke smazání ze strany uživatelů v rámci opt-out principu.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<imp:EmailList>

<imp:typeOfRecord>Active</imp:typeOfRecord>

</imp:EmailList>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<EmailListResponse xmlns="https://ws.gemilot.com/ImportExport">

<EmailList xmlns="https://ws.gemilot.com/ImportExport/EmailList">


<ListOfEmails>

<EmailAddress>[email protected]</EmailAddress>

<Email_ID>{C579BF89-2157-86B6-6832-8184C2032EB1}</Email_ID>

<Contact_ID>{7189401D-0F1E-F021-7287-AE21C11F8ABA}</Contact_ID>

<Status>Active</Status>

</ListOfEmails>

<ListOfEmails>


<Email_ID>64efa242-b008-11e3-9cb5-9c8e99c49306</Email_ID>

<Contact_ID>64ef9e8f-b008-11e3-9cb5-9c8e99c49306</Contact_ID>


</ListOfEmails>

<ListOfEmails>


<Email_ID>64efadb6-b008-11e3-9cb5-9c8e99c49306</Email_ID>

Verze 1.0.1.1 ze dne 03. 04. 2014 19 / 38

<Contact_ID>64efaa14-b008-11e3-9cb5-9c8e99c49306</Contact_ID>


</ListOfEmails>

<ListOfEmails>


<Email_ID>6e2edb0e-2532-4161-9ea4-1e9bc5914c84</Email_ID>

<Contact_ID>ba776441-d9f2-4806-9e84-f22a835a585f</Contact_ID>


</ListOfEmails>

</EmailList>

</EmailListResponse>

</soap:Body>

</soap:Envelope>

10.4 Metoda: FullContactList() Tato metoda slouží pro úplný výpis objektů kontaktů z pohledu klienta. To znamená, že zde se

vypisují všechna vyplněná data pro jednotlivé kontakty klienta, včetně e-mailové adresy a dalších

atributů, které jsou vyplněny a podporovány v systému GUC.

Rozdílem proti metodě EmailList() je tedy ten, že zatímco výše uvedená metoda zobrazuje výpis

pouze e-mailových adres; tato metoda zobrazuje údaje všechny.

Metoda poskytuje klientovi komplexní odpověď formou vždy úplných dat, které jsou k okamžiku

dotazu právě platné v systému GUC.



typeOfRecord Y Enum(Active, Inactive, Active_Inactive, Deleted)

Typ výstupu, který chceme získat. Možnosti:

Active: Aktivní a platné objekty.

Inactive: Neaktivní objekty, které nejsou využívány pro kampaně.

Active_Inactive: Kombinace výše uvedených dohromady.

Deleted: Objekty, které jsou označeny ke smazání ze strany uživatelů v rámci opt-out principu.



LoginStatus Int16 Stav přihlášení (viz část 12.1). ObjectQueue:<Contact_ID> String Unikátní ID objektu kontaktu, ke kterému je daná

e-mailová adresa přiřazena. ObjectQueue:<Company> String Název společnosti, pokud je uvedeno.

ObjectQueue:<Surname> String Příjmení.

ObjectQueue:<Firstname> String Jméno. ObjectQueue:<AliasNickname> String Přezdívka, alias. ObjectQueue:<Salutation> String Oslovení klienta. ObjectQueue:<Jubilee> String Výročí uvedené ve formátu YYYYMMDD.

Verze 1.0.1.1 ze dne 03. 04. 2014 20 / 38

ObjectQueue:<Language> String Identifikace kódu jazyka, ve kterém klient komunikuje. Kód jazyka je uveden v ISO 3166-15 a IETF language tag6.

ObjectQueue:<Status> Bool Stav kontaktu. ObjectQueue:<EmailQueue> Array(string

EmailAddress, string Email_ID, TypeOfContact Status)

Komplexní pole poskytnutí e-mailových adres k objektu záznamu klienta.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<imp:FullContactList>

<imp:typeOfRecord>Active</imp:typeOfRecord>

</imp:FullContactList>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<FullContactListResponse xmlns="https://ws.gemilot.com/ImportExport">

<FullContactList

xmlns="https://ws.gemilot.com/ImportExport/FullContactList">


<ContactObject>

<Contact_ID>119816</Contact_ID>

<Company>Moje s.r.o.</Company>

<Surname>Malkovič</Surname>

<FirstName>Jana</FirstName>

<AliasNickname/>

<Salutation/>

<Jubilee/>

<Language>cs</Language>

<Status>true</Status>

<EmailAddresses>

<EmailQueue>


<Email_ID>{C579BF89-2157-86B6-6832-8184C2032EB1}</Email_ID>


5 ISO 3166-1; URL: http://en.wikipedia.org/wiki/ISO_3166-1 6 IETF language tag; URL: http://en.wikipedia.org/wiki/IETF_language_tag

Verze 1.0.1.1 ze dne 03. 04. 2014 21 / 38

</EmailQueue>

</EmailAddresses>

</ContactObject>

<ContactObject>


<Company/>

<Surname>[email protected]</Surname>

<FirstName/>

<AliasNickname/>

<Salutation/>

<Jubilee/>

<Language/>


<EmailAddresses>

<EmailQueue>


<Email_ID>64efa242-b008-11e3-9cb5-9c8e99c49306</Email_ID>


</EmailQueue>

</EmailAddresses>

</ContactObject>

<ContactObject>


<Company/>

<Surname>[email protected]</Surname>

<FirstName/>

<AliasNickname/>

<Salutation/>

<Jubilee/>

<Language/>


<EmailAddresses>

<EmailQueue>


<Email_ID>64efadb6-b008-11e3-9cb5-9c8e99c49306</Email_ID>


</EmailQueue>

</EmailAddresses>

</ContactObject>

<ContactObject>


<Company/>

<Surname>john.doe</Surname>

<FirstName/>

<AliasNickname/>

<Salutation/>

<Jubilee/>

<Language/>


<EmailAddresses>

<EmailQueue>


<Email_ID>6e2edb0e-2532-4161-9ea4-1e9bc5914c84</Email_ID>


</EmailQueue>

</EmailAddresses>

</ContactObject>

</FullContactList>

</FullContactListResponse>

</soap:Body>

</soap:Envelope>

10.5 Metoda: ChangeEmailStatus() Metoda sloužící pro úpravu stavu e-mailové adresy, která je již v systému GUC importována, ovšem

její stav není v plném ztotožnění s klientovým záměrem.

Verze 1.0.1.1 ze dne 03. 04. 2014 22 / 38

Tato metoda se dá využít např. v přídech, kdy se omylem změní stav e-mailových adres, nebo se

klient domluví se svým odběratelem na změně stavu.

Je potřeba mít na mysli, že pokud odběratel zvolil, že již nechce odebírat elektronickou komunikaci

od klienta, je toto rozhodnutí pro klienta závazné dle platné legislativy země, ve které sídlí.



EmailAddress Y String E-mailová adresa odběratele, která musí existovat v systému GUC.

typeOfAction Y Enum(Deactivate, Delete)

Typ akce, která se hodlá provést s e-mailovým účtem klienta. Možnosti:

Deactivate: Deaktivace e-mailové adresy. Adresa jako taková se již nebude primárně nabízet pro rozesílání v rámci elektronické kampaně.

Delete: Označení e-mailové adresy pro její smazání.



LoginStatus Int16 Stav přihlášení (viz část 12.1). ChangeStatus Int16 Stav úpravy záznamu (viz část 12.2).


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<imp:ChangeEmailStatus>

<imp:EmailAddress>[email protected]</imp:EmailAddress>

<imp:typeOfAction>Delete</imp:typeOfAction>

</imp:ChangeEmailStatus>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

Verze 1.0.1.1 ze dne 03. 04. 2014 23 / 38

<ChangeEmailStatusResponse xmlns="https://ws.gemilot.com/ImportExport">

<ChangeEmailStatus

xmlns="https://ws.gemilot.com/ImportExport/ChangeEmailStatus">


<ChangeStatus>204</ChangeStatus>

</ChangeEmailStatus>

</ChangeEmailStatusResponse>

</soap:Body>

</soap:Envelope>

11 Rozhraní: E-mail Campaign

11.1 Věcný obsah Webová služba Email Campaign poskytuje jednu z částí výkonového rozhraní aplikace GUC pro

možnost práce s touto službou automatizovaným způsobem. Je navržena tak, aby v sobě obsahovala

všechny potřebné funkce a možnosti, které přímo souvisí s e-mailovými kampaněmi a možností jejich

správy – to proto, aby klient nemusel navazovat další komunikační kanál s dalším rozhraním.

Tato služba především zabezpečuje tyto oblasti:

Odeslání kampaně vybranému odběrateli s rozlišením:

o Jediného odběratele;

o Polem odběratelů;

o Skupinou odběratelů z GUC.

Ověření existence a validity zadaného e-mailového účtu.

Práci s přílohami kampaní.

Rozvoj této služby se plánuje kontinuálně, dle potřeb klientů. Customizované požadavky (tj.

požadavky, které nelze nabídnout ostatním klientům, protože jsou natolik personifikované, že by je

buď jistě nevyužili, nebo jen velmi okrajově) jsou řešeny individuálně vlastním rozhraním.

11.2 Metoda: getOutgoingEmails() Tato webová metoda poskytuje seznam registrovaných a validních7 e-mailových adres určených

k rozesílání e-mailových kampaní. Pouze z těchto e-mailových účtů lze e-mailové kampaně rozesílat.

Pokud klient potřebuje přidat nový e-mail k rozesílání, je potřeba tak učinit přes webové rozhraní

aplikace GUC, které je k nalezení na webové adrese https://guc.gemilot.com.



– – – –



LoginStatus Int16 Stav přihlášení (viz část 12.1).

7 Jedná se o e-maily, které jsou potvrzeny formou aktivačního odkazu. Pokud takový e-mail není potvrzen, tak byť je evidovaný ve webovém prostředí aplikace GUC, není nabízen jako platný pro rozesílání kampaní.

https://guc.gemilot.com/

Verze 1.0.1.1 ze dne 03. 04. 2014 24 / 38

Array(): ListOfEmails Array(string EmailAddress, string EmailAlias)

Seznam registrovaných e-mailů v poli. Atributy:

EmailAddress – Registrovaný e-mail.

EmailAlias – Klientský alias pro danou e-mailovou adresu.


SOAP požadavek



xmlns:ema="https://ws.gemilot.com/EmailCampaign">

<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:getOutgoingEmails/>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<getOutgoingEmailsResponse xmlns="https://ws.gemilot.com/EmailCampaign">

<getOutgoingEmails

xmlns="https://ws.gemilot.com/EmailCampaign/getOutgoingEmails">


<ListOfEmails>


<EmailAlias>Documentation Tester</EmailAlias>

</ListOfEmails>

</getOutgoingEmails>

</getOutgoingEmailsResponse>

</soap:Body>

</soap:Envelope>

11.3 Metoda: setUploadAttachment() Metoda slouží pro nahrání libovolné povolené8 přílohy na server GUC pro budoucí užití v e-mailových

kampaních.

Tuto metodu lze užít pro nahrávání dvou typů souborů:

1. Vlastní přílohy kampaní (např. Excel, Word, PDF…), které se vloží do kampaně jako

samostatná příloha pro zobrazení/spuštění.

2. Obrázkové přílohy, které jsou zakomponované do těla elektronického sdělení. Tuto možnost

lze využít pouze v případě užití HTML kampaně.

8 Seznam povolených extenzí lze najít v této dokumentaci, části 12.3

Verze 1.0.1.1 ze dne 03. 04. 2014 25 / 38



Filename Y String Název nahrávaného souboru včetně přípony. Note N String Volitelná poznámka k nahrávanému souboru. CID N String Content-ID dle RFC 23929 pro užití v HTML

kampaních. Data Y Base64 (byte[]) Vlastní data nahrávané přílohy.



LoginStatus Int16 Stav přihlášení (viz část 12.1). UploadStatus Int16 Stav nahrání přílohy kampaně (viz část 12.2). Attachment_ID string Unikátní ID přílohy, které lze využít při pozdějším

užití. Slouží pro korelaci mimo náš systém.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:setUploadAttachment>

<ema:Filename>happy_monkey.jpg</ema:Filename>

<ema:Note>Happy monkey from the USA</ema:Note>

<ema:CID>monkey_business</ema:CID>

<ema:Data>/9j/4AAQSkZJRgABAgEBLAEsAAD/4R4URXhpcTG4pRduqfzIRswalOoJFRhNfBMb6P

[..Base64..] //Z</ema:Data>

</ema:setUploadAttachment>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<setUploadAttachmentResponse xmlns="https://ws.gemilot.com/EmailCampaign">

<setUploadAttachment

xmlns="https://ws.gemilot.com/EmailCampaign/setUploadAttachment">


<UploadStatus>200</UploadStatus>

<Attachment_ID>82a77280-930f-4c34-8fc6-132e2f9c46ae</Attachment_ID>

9 https://tools.ietf.org/html/rfc2392

Verze 1.0.1.1 ze dne 03. 04. 2014 26 / 38

</setUploadAttachment>

</setUploadAttachmentResponse>

</soap:Body>

</soap:Envelope>

11.4 Metoda: getListOfAttachments() Metoda slouží pro zobrazení úplného listu/seznamu všech nahraných příloh pod klientský účet pro

užití v e-mailových kampaních.

Ke každé příloze ve výpise jsou navíc doplněny základní údaje pro primitivní zacházení s ní.



– – – –



LoginStatus Int16 Stav přihlášení (viz část 12.1). ListOfAttachments:<Attachment_ID> String Unikátní ID přílohy v rámci systému GUC,

který lze použít v budoucnu pro vlastní korelaci záznamu.

ListOfAttachments:<Filename> String Název nahrávaného souboru včetně přípony.

ListOfAttachments:<FileSize> UInt64 Velikost přílohy v bytech. ListOfAttachments:<Note> String Volitelná poznámka k nahrávanému

souboru.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:getListOfAttachments/>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<getListOfAttachmentsResponse xmlns="https://ws.gemilot.com/EmailCampaign">

<getListOfAttachments

xmlns="https://ws.gemilot.com/EmailCampaign/getListOfAttachments">


Verze 1.0.1.1 ze dne 03. 04. 2014 27 / 38

<ListOfAttachments>

<Attachment_ID>82a77280-930f-4c34-8fc6-132e2f9c46ae</Attachment_ID>

<Filename>happy_monkey.jpg</Filename>

<FileSize>273603</FileSize>

<Note>Happy monkey from the USA</Note>

</ListOfAttachments>

</getListOfAttachments>

</getListOfAttachmentsResponse>

</soap:Body>

</soap:Envelope>

11.5 Metoda: getDownloadAttachment() Metoda slouží pro zobrazení úplného listu/seznamu všech nahraných příloh pod klientský účet pro

užití v e-mailových kampaních.

Ke každé příloze ve výpise jsou navíc doplněny základní údaje pro primitivní zacházení s ní.



Attachment_ID Y String Unikátní ID přílohy v rámci systému GUC.



LoginStatus Int16 Stav přihlášení (viz část 12.1). Data Base64 (byte[]) Vlastní data přílohy. V pozadí systému je s nimi zacházeno

jako s polem bajtů, nicméně z důvodu funkcionality via SOAP protokol je s tím navenek (z/od klienta) nakládáno jako s Base64 kódováním. Pro správné zobrazení či práci s takto staženou přílohou je ji potřeba konvertovat z Base64 do Byte-Array a uložit na disk či do vyhrazené části paměti.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:getDownloadAttachment>

<ema:Attachment_ID>82a77280-930f-4c34-8fc6-

132e2f9c46ae</ema:Attachment_ID>

</ema:getDownloadAttachment>

</soap:Body>

</soap:Envelope>

SOAP odpověď

Verze 1.0.1.1 ze dne 03. 04. 2014 28 / 38




<soap:Body>

<getDownloadAttachmentResponse xmlns="https://ws.gemilot.com/EmailCampaign">

<getDownloadAttachment

xmlns="https://ws.gemilot.com/EmailCampaign/getDownloadAttachment">


<Data>/9j/4AAQSkZJRgABAgEBLAEsAAD/4R4URXhpcTG4pRduqfzIRswalOoJFRhNfBMb6P

[..Base64..] //Z</Data>

</getDownloadAttachment>

</getDownloadAttachmentResponse>

</soap:Body>

</soap:Envelope>

11.6 Metoda: sendMailByString() Tato metoda slouží ke komplexnímu zpracování e-mailové kampaně, včetně všech atributů, které

mohou být potřeba.

Z této bazální metody se případně derivují metody jiné, které pouze filtrují vstupní data od klienta

(např. pro zjednodušení procesu zacházení s metodou).

Aby se kampaň pomocí této metody korektně zpracovala, je potřeba dodržet několik základních

pravidel:

1. Odchozí e-mail (tj. e-mail, který se zobrazí příjemci při obdržení kampaně v poli „From:“ musí

být v systému GUC založen a aktivován. Tuto činnost lze provést výhradně přes grafické

rozhraní aplikace.

2. Pro všechny e-mailové adresy v poli „To:“ platí, že na každý mail bude rozesláno jedno

sdělení. Tj. bude využito procesu „one-by-one“, kdy pokud je zde uvedeno např. 8 e-

mailových adres, bude odesláno touto metodou 8 e-mailových sdělení v rámci jedné

kampaně.

a. Zde současně platí, že dochází k automatické kontrole na platnost zápisu e-mailové

adresy a současně dochází ke kontrole, zda zadaný e-mail se již nenachází v databázi

odběratelů klienta.

3. Všichni odběratelé uvedené v poli „Cc:“ a „Bcc:“ (tj. kopie a skryté kopie) budou použity pro

všechny odběratele uvedené v poli „To:“ totožně v rámci dané kampaně.

a. Zde rovněž platí stejná podmínka, jako uvedená v bodě 2. a. tohoto odstavce.

UP

OZO

RN

ĚNÍ

Při volání této webové metody je potřeba myslet na fakt, že díky polím To<>/Cc<>/Bcc<> se značně prodlužuje komunikace mezi klientskou a serverovou částí GUC z důvodu vyššího objemu přenášených dat. Přenos dat je potřeba uskutečnit v maximální délce 300 vteřin (5 minut). Pokud se přenos dat nestihne v tomto intervalu, webová metoda skončí spojení chybou „Connection Time-Out“. Možnosti obejití násilného ukončení spojení jsou dvě:

1. Odeslat data kampaně v několika částech, kdy se požadavky na WS GUC bude lišit pouze obsahem pole SubscriberEmails<>;

2. Požádat technickou podporu GUC o nastavení individuálního limitu přenášení dat na delší časový úsek;

3. Požádat o vyhrazení dedikované linky spojení pro vybranou IP adresu či rozsah IP adres klienta. Jako možnosti dedikované linky jsou hodnoty 10/100/1000 Mbps a také 10 Gbps (platí pouze pro Evropu).

Verze 1.0.1.1 ze dne 03. 04. 2014 29 / 38



CampaignTitle Y String Název kampaně, pod kterým lze uživatelsky kampaň identifikovat. Co kampaň, by mělo platit, že unikátní tento název.

CampaignDescription N String Volitelný popis či poznámka k názvu rozesílané kampaně.

SenderEmail Y String E-mail, ze kterého se kampaň bude rozesílat. Tento e-mail musí být v systému GUC pod klientským účtem registrovaný a aktivovaný. Jiný e-mail nelze použít.

To<> Y String[] Seznam odběratelů elektronického sdělení. Vstupem je nativní seznam e-mailových adres.

Cc<> N String[] Seznam odběratelů, kteří se mají propagovat do části kopie. Vstupem je nativní seznam e-mailových adres.

Bcc<> N String[] Seznam odběratelů, kteří se mají propagovat do části skryté kopie. Vstupem je nativní seznam e-mailových adres.

Subject Y String Předmět e-mailu. Priority Y Enum(Low,

Normal, High) Priorita e-mailu. Default: Normal

MailType Y Enum(HTML, Plain)

Typ elektronického sdělení. Zda se kampaň bude rozesílat jako HTML nebo obyčejný text. Default: Plain

Body Y String Vlastní tělo elektronického sdělení.

Attachment<> N String[] Seznam příloh elektronického sdělení, které se mají zobrazit separátně. Tj. mimo vlastní tělo zprávy. Pro korelaci je potřeba použít interní ID systému GUC.

SendFrom N String Datum a čas počátku rozesílání dle ISO 8601. Formát: YYYY-MM-DDTHH:MM:SS Příklad: 2014-02-12T16:33:00

SendTo N String Datum a čas konce rozesílání dle ISO 8601. Formát: YYYY-MM-DDTHH:MM:SS Příklad: 2014-02-12T16:33:00

DeliveryReport N Boolean Vracet informace o doručení e-mailové zprávy klientovi?

Verze 1.0.1.1 ze dne 03. 04. 2014 30 / 38

Pokud true, tak platí, že tyto doručenky přijdou na odchozí e-mail kampaně uvedeného v poli SenderEmail.

ReadReport N Boolean Vracet informace o přečtení e-mailové zprávy klientovi? Pokud true, tak platí, že tyto doručenky přijdou na odchozí e-mail kampaně uvedeného v poli SenderEmail.



LoginStatus Int16 Stav přihlášení (viz část 12.1). CampaignStatus Int16 Stav odeslané kampaně (viz část 12.2). CampaignGUID String Unikátní ID rozesílané kampaně, pod kterým ji lze

jednoznačně identifikovat i klienty. Toto ID mohou také klienti použít pro hlášení incidentů v rámci Abuse reportingu10.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:sendMailByString>

<ema:CampaignTitle>First campaign</ema:CampaignTitle>

<ema:CampaignDescription>This is my first e-mail campaign for

documentation process only</ema:CampaignDescription>

<ema:SenderEmail>[email protected]</ema:SenderEmail>

<ema:To>

<ema:string>[email protected]</ema:string>

</ema:To>

<ema:Cc>


</ema:Cc>

<ema:Bcc>


</ema:Bcc>

<ema:Subject>Hello world!</ema:Subject>

<ema:Body><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0

Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<title>Hello world!</title>

10 http://www.gemilot.com/support/abuse-desk/

Verze 1.0.1.1 ze dne 03. 04. 2014 31 / 38

</head>

<body>

<h1>Hello world [[email]]</h1>

</body></html>]]></ema:Body>

<ema:Attachment>

<ema:string>82a77280-930f-4c34-8fc6-132e2f9c46ae</ema:string>

</ema:Attachment>

<ema:SendFrom/>

<ema:SendTo/>

<ema:Priority>Normal</ema:Priority>

<ema:MailType>HTML</ema:MailType>

<ema:DeliveryReport>false</ema:DeliveryReport>

<ema:ReadReport>false</ema:ReadReport>

</ema:sendMailByString>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<sendMailByStringResponse xmlns="https://ws.gemilot.com/EmailCampaign">

<sendMailByString

xmlns="https://ws.gemilot.com/EmailCampaign/sendMailByString">


<CampaignStatus>200</CampaignStatus>

<CampaignGUID>e1be6fd8-d867-4186-9040-5d28e10aea16</CampaignGUID>

</sendMailByString>

</sendMailByStringResponse>

</soap:Body>

</soap:Envelope>

11.7 Metoda: simpleSendSingleMail() Jedná se o primitivní metodu, derivát metody Metoda: sendMailByString().

Funkcionalita je totožná z výše uvedenou metodou, pouze je omezena o některé vstupní parametry,

které nejsou pro všechny klienty podstatné. Je zachována tedy pouze podstata vlastní e-mailové

kampaně bez „zbytečností“.



CampaignTitle Y String Název kampaně, pod kterým lze uživatelsky kampaň identifikovat. Co kampaň, by mělo platit, že unikátní tento název.

CampaignDescription N String Volitelný popis či poznámka k názvu rozesílané kampaně.

SenderEmail Y String E-mail, ze kterého se kampaň bude rozesílat. Tento e-mail musí být v systému GUC pod klientským účtem registrovaný a aktivovaný. Jiný e-mail nelze použít.

To<> Y String[] Seznam odběratelů elektronického sdělení. Vstupem je nativní seznam e-mailových adres.

Subject Y String Předmět e-mailu.

Verze 1.0.1.1 ze dne 03. 04. 2014 32 / 38

Priority Y Enum(Low, Normal, High)

Priorita e-mailu. Default: Normal

MailType Y Enum(HTML, Plain)

Typ elektronického sdělení. Zda se kampaň bude rozesílat jako HTML nebo obyčejný text. Default: Plain

Body Y String Vlastní tělo elektronického sdělení. Attachment<> N String[] Seznam příloh elektronického sdělení, které se

mají zobrazit separátně. Tj. mimo vlastní tělo zprávy. Pro korelaci je potřeba použít interní ID systému GUC.



LoginStatus Int16 Stav přihlášení (viz část 12.1). CampaignStatus Int16 Stav odeslané kampaně (viz část 12.2). CampaignGUID String Unikátní ID rozesílané kampaně, pod kterým ji lze

jednoznačně identifikovat i klienty. Toto ID mohou také klienti použít pro hlášení incidentů v rámci Abuse reportingu11.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:simpleSendSingleMail>

<ema:CampaignTitle>First campaign</ema:CampaignTitle>

<ema:CampaignDescription>This is my first e-mail campaign for

documentation process only</ema:CampaignDescription>

<ema:SenderEmail>[email protected]</ema:SenderEmail>

<ema:To>[email protected]</ema:To>

<ema:Subject>Hello world!</ema:Subject>

<ema:Body><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0

Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<title>Hello world!</title>

</head>

11 http://www.gemilot.com/support/abuse-desk/

Verze 1.0.1.1 ze dne 03. 04. 2014 33 / 38

<body>

<h1>Hello world [[email]]</h1>

</body></html>]]></ema:Body>

<ema:Attachment>

<ema:string>82a77280-930f-4c34-8fc6-132e2f9c46ae</ema:string>

</ema:Attachment>

<ema:Priority>Normal</ema:Priority>

<ema:MailType>HTML</ema:MailType>

</ema:simpleSendSingleMail>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<sendMailByStringResponse xmlns="https://ws.gemilot.com/EmailCampaign">

<sendMailByString

xmlns="https://ws.gemilot.com/EmailCampaign/sendMailByString">


<CampaignStatus>200</CampaignStatus>

<CampaignGUID>7001f9cd-dab1-4521-ba4d-d136ba532316</CampaignGUID>

</sendMailByString>

</sendMailByStringResponse>

</soap:Body>

</soap:Envelope

11.8 Metoda: getVerificationSingleEmailAddress() Metoda slouží k ověření existence zadaného e-mailového účtu na vybrané doméně. Paralelně s tím se

současně ověřuje i formát zadané e-mailové adresy, zda odpovídá standardům RFC 2822 a 532212.

Funkcionalita této metody je následující:

1. Přijme se vstupní e-mail.

2. Zkontroluje se, zda odpovídá výše zmíněným RFC.

a. Pokud nevyhovuje, webová metoda vrátí chybové hlášení s informací, že zadaný e-

mail je chybný.

b. Pokud vyhovuje, pokračuje se dál.

3. Z části za zavináčem (@) se identifikuje doména, včetně koncovky (např. gmail.com).

4. Zkontroluje se, zda pro danou doménu existují DNS MX záznamy.

a. Pokud neexistují, nemůže daná doména obsluhovat poštovní služby. Proto webová

metoda skončí chybou s udáním tohoto důvodu.

b. Pokud existují, pokračuje se dál.

5. Naváže se spojení s poštovním serverem, který má uvedenou nejnižší prioritu MX DNS

záznamu a provede se spojení s dotazem, zda poštovní server zná/má informace k zadanému

poštovnímu účtu.

a. Toto se může realizovat iteračně ve dvou krocích. V prvním kroku zpravidla poštovní

server odpoví negativně. To z důvodu boje proti SPAMu a tzv. metody grey-listing.

Pokud se tak stane, u dané e-mailové adresy je potřeba dotaz opakovat znovu.

Ideálně v intervalu 300–600 vteřin (5–10 minut) od získání odpovědi.

12 Zejména se zde jedná o části 3.2.3 a 3.4.1

Verze 1.0.1.1 ze dne 03. 04. 2014 34 / 38

b. Pokud je odpověď poštovního serveru pozitivní, lze tuto e-mailovou adresu

považovat za existující.

UP

OZO

RN

ĚNÍ

Tato webová metoda validuje e-mailové adresy pouze za předpokladu, že klient má registrovaný a aktivovaný e-mailový účet pro odchozí e-mailové kampaně. Bez tohoto e-mailového účtu nelze korektně validovat e-mailové adresy, které má klient buď umístěné pod svým klientským účtem a/nebo je chce validovat pomocí této metody. Jedná se o nedílnou součást validačního procesu.



EmailAddress Y String E-mailová adresa k ověření na platnost zápisu a existenci účtu na zadané doméně.



LoginStatus Int16 Stav přihlášení (viz část 12.1). EmailAddress String Opis e-mailové adresy, na kterou se klient dotazoval. EmailStatus Int16 Vrácení stavu ověření e-mailové adresy.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:getVerificationSingleEmailAddress>

<ema:EmailAddress>[email protected]</ema:EmailAddress>

</ema:getVerificationSingleEmailAddress>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<getVerificationSingleEmailAddressResponse

xmlns="https://ws.gemilot.com/EmailCampaign">

<getVerificationSingleEmailAddress

xmlns="https://ws.gemilot.com/EmailCampaign/getVerificationSingleEmailAddress">

Verze 1.0.1.1 ze dne 03. 04. 2014 35 / 38



<EmailStatus>400</EmailStatus>

</getVerificationSingleEmailAddress>

</getVerificationSingleEmailAddressResponse>

</soap:Body>

</soap:Envelope>

11.9 Metoda: getVerificationListOfEmailAddress() Metoda je plně totožná s metodou výše popsanou, Metoda: getVerificationSingleEmailAddress().

Jejím rozšířením ovšem je to, že se touto metodou lze dotazovat na více e-mailových adres současně,

což může urychlit proces ověřování vlastní e-mailové databáze.

DO

PO

RU

ČEN

Í

Vzhledem k tomu, že výše uvedený proces je značně časově náročný na síťovou komunikaci, doporučujeme naráz ověřovat maximálně 25 e-mailových adres současně. Webová metoda je nicméně uzpůsobena tak, aby maximální počet e-mailových adres, naráz testovaných, byl 50. Při překročení této hodnoty webové metoda končí chybou a informací o překročení maximálního počtu e-mailových adres.



EmailList<> Y String[] Seznam e-mailových adres k hromadnému ověření.



LoginStatus Int16 Stav přihlášení (viz část 12.1). ProgressStatus Int16 Stav práce webové služby při ověřování. EmailInformation:<Email> String Vlastní e-mailová adresa k ověření.

EmailInformation:<EmailStatus> Int16 Stav ověření dané e-mailové adresy.


SOAP požadavek




<soap:Header>

<user:UserHeader>



</user:UserHeader>

</soap:Header>

<soap:Body>

<ema:getVerificationListOfEmailAddress>

<ema:EmailList>[email protected]</ema:EmailList>




Verze 1.0.1.1 ze dne 03. 04. 2014 36 / 38

</ema:getVerificationListOfEmailAddress>

</soap:Body>

</soap:Envelope>

SOAP odpověď




<soap:Body>

<getVerificationListOfEmailAddressResponse

xmlns="https://ws.gemilot.com/EmailCampaign">

<getVerificationListOfEmailAddress

xmlns="https://ws.gemilot.com/EmailCampaign/getVerificationListOfEmailAddress">


<ProgressStatus>200</ProgressStatus>

<EmailInformation>

<Email>[email protected]</Email>


</EmailInformation>

<EmailInformation>



</EmailInformation>

<EmailInformation>



</EmailInformation>

<EmailInformation>



</EmailInformation>

</getVerificationListOfEmailAddress>

</getVerificationListOfEmailAddressResponse>

</soap:Body>

</soap:Envelope>

12 Seznam použitých číselníků

12.1 Autentifikace

Číselníková hodnota Vysvětlení

200 Úspěch 400 Prázdná data na vstupu 401 Přístup odepřen

12.2 I/O stavy

Číselníková hodnota Vysvětlení

200 Úspěch 201 Email již existuje pro klienta 202 E-mail byl importován pod klienta 203 Úspěšně importováno 204 Úspěšně změněno 205 Reaktivovaná e-mailová adresa 401 E-mailová adresa nebyla nalezena 402 Více záznamů než povoleno 403 Jeden nebo více parametrů nebylo nalezeno 405 Nalezeno více odběratelů než bylo zakoupeno

Verze 1.0.1.1 ze dne 03. 04. 2014 37 / 38

406 Odchozí e-mail nebyl nalezen. Kampaň stornována. 407 Žádná kampaň k rozeslání 408 Žádná data ke stažení 500 Chyba serveru 501 Nebylo implementováno 502 Chybný formát e-mailové adresy 503 Zakázaná extenze souboru 504 Chyba při tvorbě kampaně 505 Kampaň byla odvolána. Nalezeno více odběratelů, než je zakoupeno. 506 Vnitřní chyba při zpracování odběratelů

12.3 Zakázané extenze souborů

exe

bat

com

cmd

php

inc

bin

jar

dll

js

pl

rb

sh

vbs

xml

cgi

htm

html

xhtml

xht

mht

mhtml

ihtml

msi

pif

application

gadget

msp

scr

cpl

msc

vb

vbe

jse

Verze 1.0.1.1 ze dne 03. 04. 2014 38 / 38

ws

wsf

wsc

wsh

ps1

ps1xml

ps2

ps2xml

psc1

psc2

scf

lnk

inf

reg

class

chm

2013/11: gemilot webové služby

Documents