API Scrub

Clients are now able to scrub their databases or forms in real time up to 100 MB per day.

Here is a sample of our API Integration Guide

Real time email scrubbing Version – 1.1

Validation: IP Based identification of clients is hardcoded into the API. Please send us your fixed IP address that you will be using to call the API. All API calls are logged for security purposes along with IP.

Standard Input: Email Address (without any quotes or special characters). We change all emails to lowercase before processing.

Default Settings:
1) International Domains- Allowed
2) Scrub Type- Lite

Optional Settings:

1) International Domains- Y/N (Allow international domains/Reject international domains).
2) Scrub Types:
(A) Lite = 1 (B) Overhaul = 2 (C) Overdrive = 3

Note: If optional settings are not correctly formatted then system will override them and take default settings.

Outputs returned: XML coded.

<Status>Blocked</Status>
<Status>Format Error</Status>
<Status>Foreign Domain</Status>
<Status>Threat String</Status>
<Status>Departmental Email</Status>
<Status>Threat Endings</Status>
<Status>Domains Blacklist</Status>
<Status>Botclickers</Status>
<Status>RealTraps</Status>
<Status>Bounces</Status>
<Status>Complainers</Status>
<Status>Clean Lite</Status>
<Status>Reject Overhaul</Status>
<Status>Clean Overhaul</Status>
<Status>Reject Overdrive</Status>
<Status>Clean Overdrive</Status>

Sample Calls:
http://ouronlineserver/API/scrub.aspx?email=someone@domain.com [Takes Default Settings] http://ouronlineserver/API/scrub.aspx?email=someone@domain.com&International=N

http://ouronlineserver/API/scrub.aspx?email=someone@domain.com&Scrub_Type=3&International=N

FTP API

Writing a FTP Client to start the scrub automatically and Understanding Server Responses.

(1) ScrubFTP server accepts a POST request to initiate a scrubbing. The scrubbing parameters should be sent as part of URL whereas username:password should be sent as per BASIC authentication mechanism and inside WebRequest header. Here is the sample URL which will send a POST request to the server to initiate scrubbing:

Sample Request in C#:

string queryParams = “?filename=” + <fileNameToScrub> + “&option=” + <scrubOption> + “&headerpresent=” + <headerIncludedStr> + “&delim=” + <fileDelimitter> + “&emailsperdomain=” + <emailLimit> + “&foreignemails=” + <foreignEmailScrubbingStr>;

HttpWebRequest request = (HttpWebRequest)

WebRequest.Create(“http://ouronlineserver/ftpclient/StartScrub.aspx” + queryParams);

request.PreAuthenticate = true;
request.Method = “POST”;
request.Timeout = 1000000; request.Headers[System.Net.HttpRequestHeader.Authorization] = “Basic ” +

Convert.ToBase64String(Encoding.ASCII.GetBytes(<username> + “:” +

                    <password>));
            request.ContentLength = 0;

here entries inside <> are the variables/inputs.

<fileNameToScrub> can be either plain file or zip file. Must be present on ftp server.

<scrubOption> can be Lite/Overhaul/Overdrive,

<headerIncludedStr> can be true/false, This field specifies if input file has header present or not. If yes, then result files after scrubbing will use that header.

       <fileDelimitter> can be , (i.e comma) or any other delimitter

<emailLimit> must be greater than -1. If nothing sent, server uses 6 by default. This field says that a domain having emails less than or equal to the specified number will be rejected.

<foreignEmailScrubbingStr> can be true/false. Default value is false on server. This field specifies whether or not foreign email extensions such as .ac, .ad etc are to be scrubbed or not.

Sample Response receiving code in C#:

HttpWebResponse response = (HttpWebResponse)request.GetResponse(); Console.WriteLine(response.StatusCode);
Stream receiveStream = response.GetResponseStream();

Encoding encode = System.Text.Encoding.GetEncoding(“utf-8″); StreamReader readStream = new StreamReader(receiveStream, encode); Console.WriteLine(“\r\nResponse stream received.”);

Char[] read = new Char[256];
int count = readStream.Read(read, 0, 256); while (count > 0)
{

String str = new String(read, 0, count); Console.Write(str);
count = readStream.Read(read, 0, 256);

}

// Releases the resources of the response.
response.Close();
// Releases the resources of the Stream.
readStream.Close();

XML Responses

Server returns an XML response for all requests. Its client’s responsibility to read the returned stream for success or failure message.

Sample Success XML response

<?xml version=”1.0″ encoding=”utf-8″?> <response>

<code>200</code>

<desc>Started the scrub with following scrub parameters Scrub Option:Lite
EmailID limit per domain :5
Scrub all Foreign Emails :True

You will get an E-mail about result of scrubbing process.</desc> </response>

Failure XML response from ScrubFTP server: (If file to be scrubbed is not present on FTP server) 

<?xml version=”1.0″ encoding=”utf-8″?> <response>

<code>500</code>

<desc>Could not download file from ftp server. The remote server returned an error: (550) File unavailable (e.g., file not found, no access).</desc>

</response>

Once you get Successful XML response that means initial filtering is done and the scrubbing process has begun for returned parameters. After the scrubbing is completed, the rejects and clean files will be zipped together and copied inside ‘clean’ folder of the FTP server that is configured by Administrator. Email-ID of client will be used to inform both success condition and also if there were any error or Exception that was encountered during scrub process.

Responses having code other than 200 will be failures for scrubbing. Failure can be because of source IP validation, userid-password mismatch, file size being more than 100MB, etc…

FAQs:

1. Whenever a client hits server using POST request with URL http://<IP>/ftpclient/StartScrub.aspx? filename=…….<allparams> and valid username/password, server will authenticate the username:password and then contact the FTP server which is configured for this user. After downloading the file from ‘dirty’ folder and doing basic sanitization, it will return successCode to client. A new thread will start scrubbing that file. After scrubbing is done, result will be zipped and put inside ‘clean’ folder of same FTP server and Email will be sent to client. Also, if scrubbing was successful, then input file would be deleted from ‘dirty’ folder.

2. If server is already scrubbing a file for one user and same user sends another request for scrubbing (either for same file or different file), that will be rejected. An XML response with error message saying that ‘server is already scrubbing a file uploaded by you’.

3. If some wrong parameters such as emailIDlengthPerDomain or ExtractForeignEmails are sent, server will use default value for these two parameters.

4. FileName, ScrubOption, HeaderPresent, ColumnDelimitter are mandatory fields and if any of them is not supplied through URL parameters, server will return error code.