feat: Add email validation endpoint

Author: elpete

ModuleConfig.cfc

@@ -4,6 +4,7 @@ component {
     this.author = "Ortus Solutions";
     this.webUrl = "https://github.com/coldbox-modules/sendgrid-sdk";
     this.entrypoint = "/sendgrid";
+    this.dependencies = [ "hyper" ];
 
     function configure() {
         routes = [ { pattern: "/webhooks", handler: "webhooks", action: "handle" } ];
@@ -25,4 +26,13 @@ component {
         };
     }
 
+    function onLoad() {
+		binder.map( "SendGridHyperClient@sendgrid-sdk" )
+			.to( "hyper.models.HyperBuilder" )
+			.asSingleton()
+			.initWith(
+				baseURL = "https://api.sendgrid.com"
+			);
+	}
+
 }

README.md

@@ -2,7 +2,43 @@
 
 [![Master Branch Build Status](https://img.shields.io/travis/coldbox-modules/sendgrid-sdk/master.svg?style=flat-square&label=master)](https://travis-ci.org/coldbox-modules/sendgrid-sdk)
 
-## An API for interacting with SendGrid, including sending emails and receiving webhooks
+## An API for interacting with SendGrid, including sending emails, validating email addresses, and receiving webhooks
+
+### Email Validation
+
+Leverage the SendGrid API to validate email addresses.  SendGrid will provide
+a validation result, score, and test results to help you determine the validity
+of an email address.
+
+#### Setup
+
+Configure your SendGrid API key credentials in the `config/ColdBox.cfc` file.
+
+Note: SendGrid uses a Bearer API token header for authentication with their API.
+The SendGrid API Keys can have different permissions granted and email address
+validation is typically seperate from all other permission sets.
+
+
+```
+moduleSettings = {
+    "sendgrid-sdk" = {
+        emailValidationAPIKey = ""
+    }
+};
+```
+
+#### Methods
+
+##### validate
+
+Validate the provided email address. Returns a configured `HyperRequest` instance.
+
+| Name           | Type          | Required? | Default | Description                                                                      |
+| -------------- | ------------- | --------- | ------- | -------------------------------------------------------------------------------- |
+| email          | String        | `true`    |         | The email address to validate                                                    |
+| source         | String        | `false`   |         | An optional text string that identifies the source of the email address          |
+
+
 
 ### Webhooks
 
@@ -27,7 +63,7 @@ correspond with:
 
 The `interceptData` is the data sent from Sendgrid.
 
-### Basic Authentication
+#### Basic Authentication
 
 SendGrid supports basic authentication when calling your webhook.
 To set this up, provide a `username` and `password` in your `moduleSettings`:
@@ -41,4 +77,4 @@ moduleSettings = {
 };
 ```
 
-Note: if you only a username or a password, `sendgrid-sdk` will return a 500 error.
+Note: if you only a username or a password, `sendgrid-sdk` will return a 500 error.

box.json

@@ -14,12 +14,15 @@
     "location": "forgeboxStorage",
     "shortDescription": "An API for interacting with SendGrid, including sending emails and receiving webhooks",
     "description": "An API for interacting with SendGrid, including sending emails and receiving webhooks",
-    "dependencies":{},
+    "dependencies":{
+        "hyper":"^3.6.2"
+    },
     "devDependencies":{
         "coldbox":"^6.0.0",
         "testbox":"^4.0.0"
     },
     "installPaths":{
+        "hyper":"modules/hyper/",
         "coldbox":"tests/resources/app/coldbox/",
         "testbox":"testbox/"
     },

models/SendGridClient.cfc

@@ -0,0 +1,46 @@
+/**
+ * Interact with the SendGrid API
+ */
+component singleton accessors="true" {
+
+	/**
+	 * The configured SendGrid API Key for Email Validation
+	 */
+	property name="emailValidationAPIKey" inject="box:setting:emailValidationAPIKey@sendgrid-sdk";
+
+	/**
+	 * A configured HyperBuilder client to use with the SendGrid API.
+	 * This is handled for you when using as a ColdBox module.
+	 */
+	property name="hyperClient" inject="SendGridHyperClient@sendgrid-sdk";
+
+	/**
+	 * Validate an email address
+	 *
+	 * @email          The email address to validate
+	 * @source	       An optional text string that identifies the source of the email address
+	 *
+	 * @returns        A configured HyperRequest instance.
+	 */
+	function validate( required string email, string source ) {
+		var reqBody = { "email": arguments.email };
+		if( structKeyExists( arguments, "source" ) && len( arguments.source ) ){
+			reqBody[ "source" ] = arguments.source;
+		}
+
+		return newRequest()
+			.setUrl( "/v3/validations/email" )
+			.setMethod( "POST" )
+			.withHeaders( { "Authorization": "Bearer #emailValidationAPIKey#" } )
+			.setBody( reqBody );
+	}
+
+	function newRequest() {
+		return variables.hyperClient.new();
+	}
+
+	function onMissingMethod( missingMethodName, missingMethodArguments ) {
+		return invoke( newRequest(), missingMethodName, missingMethodArguments );
+	}
+
+}