2013/11: Gemilot Webové služby
description
Transcript of 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 4: Vstupní parametry webové metody .................................................................................... 15
Tabulka 5: Vstupní parametry webové metody .................................................................................... 16
Tabulka 6: Výstupní data metody .......................................................................................................... 16
Tabulka 5: Vstupní parametry webové metody .................................................................................... 17
Tabulka 6: Výstupní data metody .......................................................................................................... 17
Tabulka 5: Vstupní parametry webové metody .................................................................................... 19
Tabulka 6: Výstupní data metody .......................................................................................................... 19
Tabulka 5: Vstupní parametry webové metody .................................................................................... 22
Tabulka 6: Výstupní data metody .......................................................................................................... 22
Tabulka 7: Vstupní parametry webové metody .................................................................................... 23
Tabulka 8: Výstupní data metody .......................................................................................................... 23
Tabulka 7: Vstupní parametry webové metody .................................................................................... 25
Tabulka 8: Výstupní data metody .......................................................................................................... 25
Tabulka 7: Vstupní parametry webové metody .................................................................................... 26
Tabulka 8: Výstupní data metody .......................................................................................................... 26
Tabulka 7: Vstupní parametry webové metody .................................................................................... 27
Tabulka 8: Výstupní data metody .......................................................................................................... 27
Tabulka 7: Vstupní parametry webové metody .................................................................................... 29
Tabulka 8: Výstupní data metody .......................................................................................................... 30
Tabulka 7: Vstupní parametry webové metody .................................................................................... 31
Verze 1.0.1.1 ze dne 03. 04. 2014 5 / 38
Tabulka 8: Výstupní data metody .......................................................................................................... 32
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
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.
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ěď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
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
Parametr Povinný Definiční obor Poznámka
– – – –
9.3.3 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
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:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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
Parametr Povinný Definiční obor Poznámka
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
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:imp="https://ws.gemilot.com/ImportExport">
Verze 1.0.1.1 ze dne 03. 04. 2014 17 / 38
<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>
<imp:ImportSingleEmailContact>
<imp:EmailAddress>[email protected]</imp:EmailAddress>
</imp:ImportSingleEmailContact>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<ImportSingleEmailContactResponse
xmlns="https://ws.gemilot.com/ImportExport">
<ImportSingleEmailContact
xmlns="https://ws.gemilot.com/ImportExport/ImportSingleEmailContact">
<LoginStatus>200</LoginStatus>
<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.
Tabulka 7: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
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.
Tabulka 8: Výstupní data metody
Parametr Definiční obor Poznámka
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.
10.3.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:imp="https://ws.gemilot.com/ImportExport">
<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>
<imp:EmailList>
<imp:typeOfRecord>Active</imp:typeOfRecord>
</imp:EmailList>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<EmailListResponse xmlns="https://ws.gemilot.com/ImportExport">
<EmailList xmlns="https://ws.gemilot.com/ImportExport/EmailList">
<LoginStatus>200</LoginStatus>
<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>
<EmailAddress>[email protected]</EmailAddress>
<Email_ID>64efa242-b008-11e3-9cb5-9c8e99c49306</Email_ID>
<Contact_ID>64ef9e8f-b008-11e3-9cb5-9c8e99c49306</Contact_ID>
<Status>Active</Status>
</ListOfEmails>
<ListOfEmails>
<EmailAddress>[email protected]</EmailAddress>
<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>
<Status>Active</Status>
</ListOfEmails>
<ListOfEmails>
<EmailAddress>[email protected]</EmailAddress>
<Email_ID>6e2edb0e-2532-4161-9ea4-1e9bc5914c84</Email_ID>
<Contact_ID>ba776441-d9f2-4806-9e84-f22a835a585f</Contact_ID>
<Status>Active</Status>
</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.
Tabulka 9: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
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.
Tabulka 10: Výstupní data metody
Parametr Definiční obor Poznámka
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.
10.4.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:imp="https://ws.gemilot.com/ImportExport">
<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>
<imp:FullContactList>
<imp:typeOfRecord>Active</imp:typeOfRecord>
</imp:FullContactList>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<FullContactListResponse xmlns="https://ws.gemilot.com/ImportExport">
<FullContactList
xmlns="https://ws.gemilot.com/ImportExport/FullContactList">
<LoginStatus>200</LoginStatus>
<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>
<EmailAddress>[email protected]</EmailAddress>
<Email_ID>{C579BF89-2157-86B6-6832-8184C2032EB1}</Email_ID>
<Status>Active</Status>
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>
<Contact_ID>119828</Contact_ID>
<Company/>
<Surname>[email protected]</Surname>
<FirstName/>
<AliasNickname/>
<Salutation/>
<Jubilee/>
<Language/>
<Status>true</Status>
<EmailAddresses>
<EmailQueue>
<EmailAddress>[email protected]</EmailAddress>
<Email_ID>64efa242-b008-11e3-9cb5-9c8e99c49306</Email_ID>
<Status>Active</Status>
</EmailQueue>
</EmailAddresses>
</ContactObject>
<ContactObject>
<Contact_ID>119829</Contact_ID>
<Company/>
<Surname>[email protected]</Surname>
<FirstName/>
<AliasNickname/>
<Salutation/>
<Jubilee/>
<Language/>
<Status>true</Status>
<EmailAddresses>
<EmailQueue>
<EmailAddress>[email protected]</EmailAddress>
<Email_ID>64efadb6-b008-11e3-9cb5-9c8e99c49306</Email_ID>
<Status>Active</Status>
</EmailQueue>
</EmailAddresses>
</ContactObject>
<ContactObject>
<Contact_ID>119842</Contact_ID>
<Company/>
<Surname>john.doe</Surname>
<FirstName/>
<AliasNickname/>
<Salutation/>
<Jubilee/>
<Language/>
<Status>true</Status>
<EmailAddresses>
<EmailQueue>
<EmailAddress>[email protected]</EmailAddress>
<Email_ID>6e2edb0e-2532-4161-9ea4-1e9bc5914c84</Email_ID>
<Status>Active</Status>
</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í.
Tabulka 11: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
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í.
Tabulka 12: Výstupní data metody
Parametr Definiční obor Poznámka
LoginStatus Int16 Stav přihlášení (viz část 12.1). ChangeStatus Int16 Stav úpravy záznamu (viz část 12.2).
10.5.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:imp="https://ws.gemilot.com/ImportExport">
<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>
<imp:ChangeEmailStatus>
<imp:EmailAddress>[email protected]</imp:EmailAddress>
<imp:typeOfAction>Delete</imp:typeOfAction>
</imp:ChangeEmailStatus>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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">
<LoginStatus>200</LoginStatus>
<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.
Tabulka 13: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
– – – –
Tabulka 14: Výstupní data metody
Parametr Definiční obor Poznámka
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í.
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.
11.2.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<ema:getOutgoingEmails/>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<getOutgoingEmailsResponse xmlns="https://ws.gemilot.com/EmailCampaign">
<getOutgoingEmails
xmlns="https://ws.gemilot.com/EmailCampaign/getOutgoingEmails">
<LoginStatus>200</LoginStatus>
<ListOfEmails>
<EmailAddress>[email protected]</EmailAddress>
<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
Tabulka 15: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
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.
Tabulka 16: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.3.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<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:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<setUploadAttachmentResponse xmlns="https://ws.gemilot.com/EmailCampaign">
<setUploadAttachment
xmlns="https://ws.gemilot.com/EmailCampaign/setUploadAttachment">
<LoginStatus>200</LoginStatus>
<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í.
Tabulka 17: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
– – – –
Tabulka 18: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.4.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<ema:getListOfAttachments/>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<getListOfAttachmentsResponse xmlns="https://ws.gemilot.com/EmailCampaign">
<getListOfAttachments
xmlns="https://ws.gemilot.com/EmailCampaign/getListOfAttachments">
<LoginStatus>200</LoginStatus>
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í.
Tabulka 19: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
Attachment_ID Y String Unikátní ID přílohy v rámci systému GUC.
Tabulka 20: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.5.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<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:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<getDownloadAttachmentResponse xmlns="https://ws.gemilot.com/EmailCampaign">
<getDownloadAttachment
xmlns="https://ws.gemilot.com/EmailCampaign/getDownloadAttachment">
<LoginStatus>200</LoginStatus>
<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
Tabulka 21: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
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.
Tabulka 22: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.6.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<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:string>[email protected]</ema:string>
</ema:Cc>
<ema:Bcc>
<ema:string>[email protected]</ema:string>
</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:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<sendMailByStringResponse xmlns="https://ws.gemilot.com/EmailCampaign">
<sendMailByString
xmlns="https://ws.gemilot.com/EmailCampaign/sendMailByString">
<LoginStatus>200</LoginStatus>
<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í“.
Tabulka 23: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
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.
Tabulka 24: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.7.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<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:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<sendMailByStringResponse xmlns="https://ws.gemilot.com/EmailCampaign">
<sendMailByString
xmlns="https://ws.gemilot.com/EmailCampaign/sendMailByString">
<LoginStatus>200</LoginStatus>
<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.
Tabulka 25: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
EmailAddress Y String E-mailová adresa k ověření na platnost zápisu a existenci účtu na zadané doméně.
Tabulka 26: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.8.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<ema:getVerificationSingleEmailAddress>
<ema:EmailAddress>[email protected]</ema:EmailAddress>
</ema:getVerificationSingleEmailAddress>
</soap:Body>
</soap:Envelope>
SOAP odpověď
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<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
<LoginStatus>200</LoginStatus>
<EmailAddress>[email protected]</EmailAddress>
<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.
Tabulka 27: Vstupní parametry webové metody
Parametr Povinný Definiční obor Poznámka
EmailList<> Y String[] Seznam e-mailových adres k hromadnému ověření.
Tabulka 28: Výstupní data metody
Parametr Definiční obor Poznámka
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.
11.9.1.1 Příklady komunikace formou SOAP zpráv
SOAP požadavek
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:user="https://ws.gemilot.com/ISecurityChannel/User"
xmlns:ema="https://ws.gemilot.com/EmailCampaign">
<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>
<ema:getVerificationListOfEmailAddress>
<ema:EmailList>[email protected]</ema:EmailList>
<ema:EmailList>[email protected]</ema:EmailList>
<ema:EmailList>[email protected]</ema:EmailList>
<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:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<getVerificationListOfEmailAddressResponse
xmlns="https://ws.gemilot.com/EmailCampaign">
<getVerificationListOfEmailAddress
xmlns="https://ws.gemilot.com/EmailCampaign/getVerificationListOfEmailAddress">
<LoginStatus>200</LoginStatus>
<ProgressStatus>200</ProgressStatus>
<EmailInformation>
<Email>[email protected]</Email>
<EmailStatus>400</EmailStatus>
</EmailInformation>
<EmailInformation>
<Email>[email protected]</Email>
<EmailStatus>400</EmailStatus>
</EmailInformation>
<EmailInformation>
<Email>[email protected]</Email>
<EmailStatus>200</EmailStatus>
</EmailInformation>
<EmailInformation>
<Email>[email protected]</Email>
<EmailStatus>200</EmailStatus>
</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