Onlinespamfilter gebruiker documentatie
API documentatie
- gerard.vandijnsen@onlinespamfilter.nl
Inleiding
Onlinespamfilter biedt haar resellers de mogelijkheid een aantal veel voorkomende handelingen uit te voeren via een API. Deze API kan via https://api.onlinespamfilter.nl worden aangesproken. API toegang is alleen op aanvraag beschikbaar voor resellers. U kunt hiervoor contact opnemen met uw contactpersoon binnen http://Onlinespamfilter.nl .
De Onlinespamfilter API communiceert middels XML en luistert naar HTTP requests van het type GET, POST, PUT, UPDATE en DELETE. Alleen de GET en POST requests zijn in web browsers gedefinieerd. Voor de volledige functionaliteit zult u dus een eigen client moeten schrijven of u kunt gebruik maken van een tool als cURL (http://curl.haxx.se). De API zal proberen antwoord te geven middels een XML object of een XML error object. In geval van onverwachte fouten kan een html pagina worden teruggegeven. Houd hier rekening mee tijdens het programmeren van uw client.
Domein acties
In de API voor domeinen kan een reseller domeinen aanmaken, verwijderen en instellingen wijzigen.
Domein overzicht
URL | |
Actie | GET |
Invoer | - |
Gevolg | - |
Response | XML domein objecten voor de geauthenticeerde gebruiker |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password 'https://api.onlinespamfilter.nl/api_domains' |
Domein details
URL | |
Actie | GET |
Invoer | - |
Gevolg | - |
Response | XML object voor [domeinnaam] |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password 'https://api.onlinespamfilter.nl/api_domains/[domeinnaam]' |
Domein details aanpassen
URL | |
Actie | PUT |
Invoer | XML lijst met aan te passen attributes. Toegestane attributes zijn: transportport, transportip en testuser |
Gevolg | Domein attributes worden aangepast |
Response | XML object voor [domeinnaam] |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password -X PUT -d '<api-domain><testuser>postmaster</testuser></api-domain>' 'https://api.onlinespamfilter.nl/api_domains/[domeinnaam]' |
Domein aanmaken
URL | |
Actie | POST |
Invoer | XML object met correcte attributes voor aan te maken domein. Verplichte attributes: domain, testuser, transportip, transportport. |
Gevolg | Domein wordt aangemaakt |
Response | XML object van het aangemaakte domein |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password -X POST -d '<api-domain><domain>new-domein.nl</domain><testuser>postmaster</testuser><transportip>mail.new-domain.com</transportip><transportport>2525</transportport></api-domain>' 'https://api.onlinespamfilter.nl/api_domains' |
Domein verwijderen
URL | |
Actie | DELETE |
Invoer | - |
Gevolg | Indien toegestaan wordt domein verwijderd. Eventuele geschiedenis of andere verwante gegevens verdwijnen hiermee ook! |
Response | Een ok response in de HTML header. Geen object. |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password -X DELETE 'https://api.onlinespamfilter.nl/api_domains/[domeinnaam]' |
DomeinAlias acties
In de API voor domeinen aliases kan momenteel alleen een overzicht geven van de ingestelde domein aliasen.
DomeinAlias overzicht
URL | |
Actie | GET |
Invoer | - |
Gevolg | - |
Response | XML domein alias objecten voor de geauthenticeerde gebruiker |
Voorbeeld | curl -k -H ‘Accept: application/xml' -H 'Content-Type: application/xml' -u username:password 'https://api.onlinespamfilter.nl/api_domains_aliases’ |
Berichten Historie
Wanneer een bericht in een domein is gescand krijgt het gedurende 14 dagen een vermelding in de 'history' database tabel. Middels de historie api kan een lijst van berichten worden opgevraagd per domein. Individuele berichten kunnen worden ingeleerd als spam/innocent, afhankelijk van de huidige class
Berichten overzicht
URL | |
Actie | GET |
Invoer | - |
Gevolg | - |
Response | Lijst met bericht objecten voor [domeinnaam]. Hierbij komt ook een uniek id (de osfsum) beschikbaar dat kan worden gebruikt voor inleren of opvragen berichtinhoud |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password 'https://api.onlinespamfilter.nl/api_histories/[domeinnaam]' |
Berichten corrigeren
URL | |
Actie | PUT |
Invoer | - |
Gevolg | Indien toegestaan wordt bericht gecorrigeerd in database. Het bericht wordt niet doorgestuurd naar de originele ontvanger. Hier is de reseller zelf verantwoordelijk voor. Bericht kan worden opgvraagd middels de api_messages functionaliteit. Let op: Afhankelijk van het type inleer actie kan het zijn dat de berichtinhoud later niet meer op te vragen is. Als de inhoud van het bericht nodig is moet dit dus worden opgevraagd voor de inleeractie. |
Response | XML object met bericht met nieuwe classificering |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -X PUT -d '' -u username:password 'https://api.onlinespamfilter.nl/api_histories/[osfsum]' |
Spam berichten corrigeren zonder API key
Voor berichten die zijn ontvangen door de gebruiker terwijl ze eigenlijk als spam geclassificeerd hadden moeten worden is er een mogelijkheid deze te corrigeren (Innocent → Spam) zonder dat een API key benodigd is. Dit is mogelijk omdat de unieke combinatie van domeinnaam en X-OSF-Sum header alleen bij de ontvanger van de mail bekend is. Deze functionaliteit kan bijvoorbeeld worden gebruikt om een ‘spam’ knop in een mail client te realiseren zonder dat hiervoor de API key van de reseller benodigd is. Deze methode vervangt op termijn de “retrain by mail” functionaliteit die zal worden uitgefaseerd.
Let op: Deze api call is een POST call met een JSON response.
URL | |
Actie | POST |
Invoer | domein en spamfilter ID (te vinden in X-OSF-Sum header) |
Gevolg | Alle correctie acties die zouden worden uitgevoerd door de web portal voor dit bericht worden uitgevoerd. |
Response | JSON object met {“status”: “OK”} of {“error”: “Uitleg over de error”} |
Voorbeeld | curl -X POST -F ‘domain=<domain_name>' -F 'osfsum=<Spamfilter ID>’ https://api.onlinespamfilter.nl/api_classify_spam |
Bericht inhoud
Een bericht dat niet op de eindbestemming is afgeleverd wordt in gecomprimeerde vorm tot 14 dagen bewaard. De reseller kan indien gewenst het bericht uit de database opvragen. Er wordt dan een XML object met (Zlib) gecomprimeerde berichtdata verstuurd.
URL | |
Actie | GET |
Invoer | - |
Response | XML object met de gecomprimeerde data van bericht met id [osfsum] |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password 'https://api.onlinespamfilter.nl/api_messages/[osfsum]' |
Domein Statistieken
Het is mogelijk om statistieken voor een domein op te vragen. Dit resulteert in een opsomming van de hoeveelheid spam, innocent, virus en banned berichten per dag. Het is aan de gebruiker zelf om hiervan grafieken te genereren.
URL | |
Actie | GET |
Invoer | Indien de GET parameter startdate wordt meegegeven wordt deze gebruikt als de eerste datum voor de statistieken. Indien deze parameter wordt weggelaten, wordt de start datum automatisch 14 dagen in het verleden gekozen. Het formaat van de meegegeven datum is dd-mm-yyyy |
Response | Lijst van XML objecten die een telling bevatten van de hoeveelheid spam, innocent, virus en banned berichten per dag |
Voorbeeld | curl -k -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u username:password 'https://api.onlinespamfilter.nl/api_statistics/[domeinnaam][?startdate=<datum>]' |