DE-1412 Move ValidateEmail() to MailgunImpl (#383)

examples/examples.go

@@ -608,13 +608,13 @@ func ListUnsubscribes(domain, apiKey string) ([]mailgun.Unsubscribe, error) {
 	return result, nil
 }
 
-func ValidateEmail(apiKey string) (mailgun.EmailVerification, error) {
-	mv := mailgun.NewEmailValidator(apiKey)
+func ValidateEmail(apiKey string) (mailgun.ValidateEmailResponse, error) {
+	mg := mailgun.NewMailgun(apiKey)
 
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
 	defer cancel()
 
-	return mv.ValidateEmail(ctx, "foo@mailgun.net", false)
+	return mg.ValidateEmail(ctx, "foo@mailgun.net", false)
 }
 
 func GetWebhook(domain, apiKey string) ([]string, error) {

examples_test.go

@@ -15,13 +15,13 @@ import (
 	"github.com/mailgun/mailgun-go/v4/events"
 )
 
-func ExampleEmailValidatorImpl_ValidateEmail() {
-	v := mailgun.NewEmailValidator("my_api_key")
+func ExampleMailgunImpl_ValidateEmail() {
+	mg := mailgun.NewMailgun("my_api_key")
 
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
 	defer cancel()
 
-	ev, err := v.ValidateEmail(ctx, "joe@example.com", false)
+	ev, err := mg.ValidateEmail(ctx, "joe@example.com", false)
 	if err != nil {
 		log.Fatal(err)
 	}

mailgun.go

@@ -234,6 +234,8 @@ type Mailgun interface {
 	DeleteTemplateVersion(ctx context.Context, domain, templateName, tag string) error
 	ListTemplateVersions(domain, templateName string, opts *ListOptions) *TemplateVersionsIterator
 
+	ValidateEmail(ctx context.Context, email string, mailBoxVerify bool) (ValidateEmailResponse, error)
+
 	ListSubaccounts(opts *ListSubaccountsOptions) *SubaccountsIterator
 	CreateSubaccount(ctx context.Context, subaccountName string) (SubaccountResponse, error)
 	SubaccountDetails(ctx context.Context, subaccountId string) (SubaccountResponse, error)

mock_validation.go

@@ -17,7 +17,7 @@ func (ms *mockServer) validateEmailV4(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	var results EmailVerification
+	var results ValidateEmailResponse
 	results.Address = r.FormValue("address")
 	results.Reason = []string{"no-reason"}
 	results.Risk = "unknown"

validation.go

@@ -0,0 +1,69 @@
+package mailgun
+
+import (
+	"context"
+	"fmt"
+)
+
+// ValidateEmailResponse records basic facts about a validated e-mail address.
+// See the ValidateEmail method and example for more details.
+type ValidateEmailResponse struct {
+	// Echoes the address provided.
+	Address string `json:"address"`
+
+	// Indicates whether Mailgun thinks the address is from a known
+	// disposable mailbox provider.
+	IsDisposableAddress bool `json:"is_disposable_address"`
+
+	// Indicates whether Mailgun thinks the address is an email distribution list.
+	IsRoleAddress bool `json:"is_role_address"`
+
+	// A list of potential reasons why a specific validation may be unsuccessful. (Available in the v4 response)
+	Reason []string `json:"reason"`
+
+	// Result
+	Result string `json:"result"`
+
+	// Risk assessment for the provided email.
+	Risk string `json:"risk"`
+
+	LastSeen int64 `json:"last_seen,omitempty"`
+
+	// Provides a simple recommendation in case the address is invalid or
+	// Mailgun thinks you might have a typo. May be empty, in which case
+	// Mailgun has no recommendation to give.
+	DidYouMean string `json:"did_you_mean,omitempty"`
+
+	// Engagement results are a macro-level view that explain an email recipient’s propensity to engage.
+	// https://documentation.mailgun.com/docs/inboxready/mailgun-validate/validate_engagement/
+	Engagement *EngagementData `json:"engagement,omitempty"`
+
+	RootAddress string `json:"root_address,omitempty"`
+}
+
+type EngagementData struct {
+	Engaging bool   `json:"engaging"`
+	IsBot    bool   `json:"is_bot"`
+	Behavior string `json:"behavior,omitempty"`
+}
+
+// ValidateEmail performs various checks on the email address provided to ensure it's correctly formatted.
+// It may also be used to break an email address into its sub-components.
+// https://documentation.mailgun.com/docs/inboxready/mailgun-validate/single-valid-ir/
+func (mg *MailgunImpl) ValidateEmail(ctx context.Context, email string, mailBoxVerify bool) (ValidateEmailResponse, error) {
+	r := newHTTPRequest(fmt.Sprintf("%s/v4/address/validate", mg.APIBase()))
+	r.setClient(mg.HTTPClient())
+	r.addParameter("address", email)
+	if mailBoxVerify {
+		r.addParameter("mailbox_verification", "true")
+	}
+	r.setBasicAuth(basicAuthUser, mg.APIKey())
+
+	var res ValidateEmailResponse
+	err := getResponseFromJSON(ctx, r, &res)
+	if err != nil {
+		return ValidateEmailResponse{}, err
+	}
+
+	return res, nil
+}

email_validation_test.go → validation_test.go

@@ -9,13 +9,14 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func TestEmailValidationV4(t *testing.T) {
-	v := mailgun.NewEmailValidator(testKey)
-	v.SetAPIBase(server.URL())
+func TestValidateEmail(t *testing.T) {
+	mg := mailgun.NewMailgun(testKey)
+	err := mg.SetAPIBase(server.URL())
+	require.NoError(t, err)
 
 	ctx := context.Background()
 
-	ev, err := v.ValidateEmail(ctx, "foo@mailgun.com", false)
+	ev, err := mg.ValidateEmail(ctx, "foo@mailgun.com", false)
 	require.NoError(t, err)
 
 	assert.False(t, ev.IsDisposableAddress)