/// <summary>
/// Returns an object representing an email validation batch, waiting for its completion and issuing multiple retries if needed.
/// Makes a GET request to the /email-validations/{uniqueId} resource.
/// <remarks>To initiate a new email validation batch, please use <see cref="Submit(IEnumerable{string})" />.</remarks>
/// </summary>
/// <param name="uniqueId">The unique identifier for an email validation batch to be retrieved.</param>
/// <param name="waitForCompletionOptions">The options about waiting for the validation completion.</param>
/// <returns>An object representing the current status of the requested email validation batch.</returns>
public Validation Query(Guid uniqueId, WaitForCompletionOptions waitForCompletionOptions)
{
// Handle the case when the client wishes to avoid waiting for completion
if (waitForCompletionOptions == WaitForCompletionOptions.DontWait)
return QueryOnce(uniqueId);
// The client needs to wait for completion
var pollingTask = Task.Factory.StartNew(() =>
{
while (true)
{
var result = QueryOnce(uniqueId);
// A null result means the validation has not been found
if (result == null)
{
return null;
}
// Returns immediately if the validation has been completed
if (result.Status == ValidationStatus.Completed)
{
return result;
}
// Wait for the polling interval
Thread.Sleep(waitForCompletionOptions.PollingInterval);
}
});
// Waits for the request completion or for the timeout to expire
pollingTask.Wait(waitForCompletionOptions.Timeout);
// Handles any eventual exception
if (pollingTask.IsFaulted)
{
Debug.Assert(pollingTask.Exception != null, "pollingTask.Exception != null");
if (pollingTask.Exception.InnerException != null)
throw pollingTask.Exception.InnerException;
throw pollingTask.Exception;
}
if (pollingTask.IsCompleted)
{
return pollingTask.Result;
}
// A timeout occurred
return null;
}
/// <summary>
/// Initiates a new email validation batch. Makes a POST request to the /email-validations resource.
/// <remarks>Upon initialization, batches usually are in the <see cref="ValidationStatus.Pending">Pending</see> status.
/// Validations are completed only when their <see cref="Validation.Status">Status</see> property
/// is <see cref="ValidationStatus.Completed">Completed</see>; the <seealso cref="waitForCompletionOptions"/> parameter
/// allows to wait for the completion of the batch, without having to manually poll the API.
/// In order to retrieve the most up-to-date snapshot of a validation batch, call the <see cref="Query(Guid)">Query() method</see>
/// along with the batch's <see cref="Validation.UniqueID">unique identifier</see>.
/// </remarks>
/// </summary>
/// <param name="emailAddresses">A collection of email addresses to validate.</param>
/// <param name="waitForCompletionOptions">The options about waiting for the validation completion.</param>
/// <returns>An object representing the email validation batch.</returns>
public Validation Submit(IEnumerable<string> emailAddresses, WaitForCompletionOptions waitForCompletionOptions)
{
if (emailAddresses == null)
throw new ArgumentNullException("emailAddresses");
if (waitForCompletionOptions == null)
throw new ArgumentNullException("waitForCompletionOptions");
var requestEntries = emailAddresses
.Select(emailAddress => new
{
inputData = emailAddress
}).ToArray();
if (requestEntries.Length == 0)
throw new ArgumentException("Can't validate an empty batch.", "emailAddresses");
// Build the REST request
var request = new RestRequest
{
Method = Method.POST,
RequestFormat = DataFormat.Json,
Resource = "email-validations"
};
request.AddBody(new
{
entries = requestEntries
});
// Send the request to the Verifalia servers
var response = _restClient.Execute<Validation>(request);
switch (response.StatusCode)
{
case HttpStatusCode.OK:
{
// The batch has been completed in real time
response.Data.Status = ValidationStatus.Completed;
return response.Data;
}
case HttpStatusCode.Accepted:
{
// The batch has been accepted but is not yet completed
if (ReferenceEquals(waitForCompletionOptions, WaitForCompletionOptions.DontWait))
{
response.Data.Status = ValidationStatus.Pending;
return response.Data;
}
// Poll the service until completion
return Query(response.Data.UniqueID, waitForCompletionOptions);
}
case HttpStatusCode.Unauthorized:
{
// The batch has NOT been accepted because of an issue with the supplied credentials
throw new AuthorizationException(response.ErrorMessage)
{
Response = response
};
}
case HttpStatusCode.PaymentRequired:
{
// The batch has NOT been accepted because of low account credit
throw new InsufficientCreditException(response.ErrorMessage)
{
Response = response
};
}
default:
{
// An unhandled exception happened at the Verifalia side
throw new VerifaliaException(response.ErrorMessage)
{
Response = response
};
}
}
}
/// <summary>
/// Initiates a new email validation batch. Makes a POST request to the /email-validations resource.
/// <remarks>Upon initialization, batches usually are in the <see cref="ValidationStatus.Pending">Pending</see> status.
/// Validations are completed only when their <see cref="Validation.Status">Status</see> property
/// is <see cref="ValidationStatus.Completed">Completed</see>; the <seealso cref="waitForCompletionOptions"/> parameter
/// allows to wait for the completion of the batch, without having to manually poll the API.
/// In order to retrieve the most up-to-date snapshot of a validation batch, call the <see cref="Query(Guid)">Query() method</see>
/// along with the batch's <see cref="Validation.UniqueID">unique identifier</see>.
/// </remarks>
/// </summary>
/// <param name="emailAddresses">A collection of email addresses to validate.</param>
/// <param name="waitForCompletionOptions">The options about waiting for the validation completion.</param>
/// <returns>An object representing the email validation batch.</returns>
public Validation Submit(IEnumerable <string> emailAddresses, WaitForCompletionOptions waitForCompletionOptions)
{
if (emailAddresses == null)
{
throw new ArgumentNullException("emailAddresses");
}
if (waitForCompletionOptions == null)
{
throw new ArgumentNullException("waitForCompletionOptions");
}
var requestEntries = emailAddresses
.Select(emailAddress => new
{
inputData = emailAddress
}).ToArray();
if (requestEntries.Length == 0)
{
throw new ArgumentException("Can't validate an empty batch.", "emailAddresses");
}
// Build the REST request
var request = new RestRequest
{
Method = Method.POST,
RequestFormat = DataFormat.Json,
Resource = "email-validations"
};
request.AddBody(new
{
entries = requestEntries
});
// Send the request to the Verifalia servers
var response = _restClient.Execute <Validation>(request);
switch (response.StatusCode)
{
case HttpStatusCode.OK:
{
// The batch has been completed in real time
response.Data.Status = ValidationStatus.Completed;
return(response.Data);
}
case HttpStatusCode.Accepted:
{
// The batch has been accepted but is not yet completed
if (ReferenceEquals(waitForCompletionOptions, WaitForCompletionOptions.DontWait))
{
response.Data.Status = ValidationStatus.Pending;
return(response.Data);
}
// Poll the service until completion
return(Query(response.Data.UniqueID, waitForCompletionOptions));
}
case HttpStatusCode.Unauthorized:
{
// The batch has NOT been accepted because of an issue with the supplied credentials
throw new AuthorizationException(response.ErrorMessage)
{
Response = response
};
}
case HttpStatusCode.PaymentRequired:
{
// The batch has NOT been accepted because of low account credit
throw new InsufficientCreditException(response.ErrorMessage)
{
Response = response
};
}
default:
{
// An unhandled exception happened at the Verifalia side
throw new VerifaliaException(response.ErrorMessage)
{
Response = response
};
}
}
}
/// <summary>
/// Returns an object representing an email validation batch, waiting for its completion and issuing multiple retries if needed.
/// Makes a GET request to the /email-validations/{uniqueId} resource.
/// <remarks>To initiate a new email validation batch, please use <see cref="Submit(IEnumerable{string})" />.</remarks>
/// </summary>
/// <param name="uniqueId">The unique identifier for an email validation batch to be retrieved.</param>
/// <param name="waitForCompletionOptions">The options about waiting for the validation completion.</param>
/// <returns>An object representing the current status of the requested email validation batch.</returns>
public Validation Query(Guid uniqueId, WaitForCompletionOptions waitForCompletionOptions)
{
// Handle the case when the client wishes to avoid waiting for completion
if (waitForCompletionOptions == WaitForCompletionOptions.DontWait)
{
return(QueryOnce(uniqueId));
}
// The client needs to wait for completion
var pollingTask = Task.Factory.StartNew(() =>
{
while (true)
{
var result = QueryOnce(uniqueId);
// A null result means the validation has not been found
if (result == null)
{
return(null);
}
// Returns immediately if the validation has been completed
if (result.Status == ValidationStatus.Completed)
{
return(result);
}
// Wait for the polling interval
Thread.Sleep(waitForCompletionOptions.PollingInterval);
}
});
// Waits for the request completion or for the timeout to expire
pollingTask.Wait(waitForCompletionOptions.Timeout);
// Handles any eventual exception
if (pollingTask.IsFaulted)
{
Debug.Assert(pollingTask.Exception != null, "pollingTask.Exception != null");
if (pollingTask.Exception.InnerException != null)
{
throw pollingTask.Exception.InnerException;
}
throw pollingTask.Exception;
}
if (pollingTask.IsCompleted)
{
return(pollingTask.Result);
}
// A timeout occurred
return(null);
}
