Understanding email address validation with external services

What’s email address validation, and why is it important?

Email address validation, also called email verification, is a process that checks if an email address is deliverable – or, simply put, a valid email address.

For instance, many of your users may make spelling or formatting mistakes while typing in their emails, especially if they enter the information from mobile devices with small screens. Email validation catches these syntax errors or typos and assesses whether the bad data is an honest mistake, a purposeful misdirect, or a potential cybersecurity threat.

Email address validation is important because it can do the following:

• Increase delivery rate: Decrease your bounce rate by verifying email addresses and leaving out invalid users that mail servers can’t reach.

• Clean and organize your mailing list: Keep your mailing list up-to-date and organized by weeding out email addresses that are defunct or invalid.

• Drive higher conversion rate: Since you’re focusing your energies on emails that have been validated, you’re not wasting messages on invalid email addresses. This allows you to target active email recipients and achieve a higher conversion rate.

• Protect your sender reputation: Your IP address and domain reputations are the email client’s metrics used to determine whether or not to deliver your messages. They also impact whether your emails end up in your recipient’s inbox or in the spam folder. Maintain a good sender reputation by targeting email addresses with valid users.

What’s Mailgun’s email validations API?

Why leave your email campaign’s success up to chance when you can easily validate email addresses?

At Mailgun, we provide an email verification service fully integrated into our suite of email deliverability features and services. You won’t have to switch back and forth between different platforms and data sources to check if your email campaigns will bounce.

Our Email validations API can be queried at the following endpoint: https://api.mailgun.net/v4/address/validate. The API programmatically inspects multiple aspects of an email address to check the following:

• The email address syntax is correct.

• The domain is set up to receive email.

• The email address exists.

• The address doesn’t have any cached bounce events from the Mailgun network.

• The email address isn’t a high-risk address.

• The email address isn’t a role-based email address such as info@mailgun.com or admin@mailgun.com.

• The email address isn’t disposable.

• The email address doesn’t contain a typo in the domain.

• The email address isn’t at a catch-all domain.

  • If the domain is catch-all, we will mark it as deliverable if we have engagement at the address.

We know how important it is for you to maintain a list of verified and deliverable email addresses to reduce the ratio of bounced emails that may harm your sender reputation.

What are three ways to use Mailgun to validate email addresses?

Mailgun offers email address verifications in three ways:

• Verifying the email addresses of a mailing list

• Verifying a single email address

• Verifying email addresses supplied in bulk via a CSV

If you’re not ready to dive into the code, check out our Mailing List feature on our platform, as shown below. You can verify members of a Mailing List with the click of a button from your Control Panel. Remember that you can only have a maximum of 2.5 million members on your Mailing List.

If you’re up for some code, let’s go over how to perform a single email verification or a bulk email verification via our API below.

Before you get started…

Before diving into the tutorials, make sure you’ve signed up for Mailgun if you haven’t already. Once you have an account, navigate the Dashboard, click on the API Security tab, and copy your Private API Key, as shown below. You’ll need this for authentication purposes.

The following tutorials will use our Mailgun API, so familiarity with RESTful APIs, curl, and JSON is highly encouraged, but not required.

How do I use Mailgun’s email validations API to validate a single email address?

Let’s start with the most basic use case: verifying one email address. We can make a GET request to the email validations API as follows:

Remember to supply your Private API Key instead of the PRIVATE_API_KEY from the example above. In addition, you can supply the email address you’re verifying as a parameter for address.

If you’ve written your query correctly, you should get a response as follows:

The two most important parts of this response are the result and risk parameters.

The result parameter is our primary assessment of the email address you submitted for verification. It can contain the following values:

• deliverable: The recipient address is valid and should accept an email from you.

• undeliverable: The recipient address is invalid and will result in a bounce if you send a message.

• do_not_send: The recipient address is highly risky and will negatively impact your sender reputation if you send a message to this address.

• catch_all: The validity of the recipient address cannot be determined as the Email Service Provider (ESP) accepts all emails, regardless of whether or not the recipient’s mailbox exists.

• unknown: The validity of the recipient address can’t be determined for several potential reasons. Please refer to the associated reason array returned in the response.

The risk parameter is our assessment of how sending messages to a given address may impact your sender reputation. This parameter can contain the following values:

• low: The email address is likely legitimate and sending an email to this address has a low likelihood of damaging your sender reputation if the address has been obtained in a legitimate manner. 

• medium: This is our default or neutral state for risk calculation. An email address that isn’t deemed a low or high risk will default to a medium risk.

• high: An email address that has a high risk of damaging your sender reputation or when used for verification on your platform. You should examine this email address to challenge its validity.

Here’s a brief explanation of the other parameters in the response body:

• address: This returns the email address being verified.

• is_disposable_address: This key returns a value of true or false, based on whether or not the verified email is a disposable email address.

• is_role_address: This returns a value of true or false, based on whether or not the verified email address is a role address.

• reason: This array provides additional information if we can’t properly verify an email address, such as mailbox_does_not_exist or high_risk_domain. If your risk is medium or high, this array will provide an explanation.

And that’s it for performing a basic email address validation. Note that you can also perform a single email verification via a POST request. Check out our API documentation for more details.

How do I use Mailgun’s email validations API to validate bulk email addresses?

But what if you have hundreds (or thousands!) of email addresses to verify? Sending one at a time is an inefficient use of your time and computing resources.

Bulk verification allows you to verify a list of email addresses. Once the verifications have all been completed, you can access the results via a download_url link. Keep in mind, you must provide your list of email addresses as a raw CSV or GZIP. You also must upload your file as a multi-part/form-data where the file is defined by file. 

Below, let’s look at two API requests to manage your bulk verifications:

• Create a bulk verification job

• Get the status of a bulk verification job

How do I create a bulk email verification job?

Once you’ve prepped and uploaded your list of email addresses according to the specifications above, it’s easy to create a bulk email verification job. We’ll use a POST request to our email validations API as shown below:

Remember to substitute your Private API Key for YOUR_API_KEY, to name your list for LIST_NAME, and to insert the path of your file for file.

You should receive the following response:

You’ll receive a message confirming your job was successfully submitted. The id is the list name you provided.

How do I check the status of a bulk verification job?

We promise your bulk verifications won’t take very long – think minutes, not hours. We’re able to do this because our email verification tool uses our cache of billions of email addresses as its primary source to enable lightning-fast verification. But just in case you need to check the status of your bulk verification job, you can use the following GET request:

Remember to substitute your Private API Key for YOUR_API_KEY and to name your list for LIST_NAME. Here’s a sample response to your request:

You can see a summary of your email verifications, including the result and risk breakdowns. You can also see your job’s status, which is the current state of the list verification request, like created, processing, completed, uploading, uploaded, and failed.

Once your bulk verification job has been successfully uploaded, you can use the download_url links to access details about each email address in your list.

And just like that, you’ve verified your emails and you’re ready to send off your email campaign.

How do I use Mailgun’s email validations API with Salesforce’s External Services?

Let’s look at how a Salesforce administrator can configure Salesforce for use with Mailgun’s email validation API. To do so, we’ll use External Services, which is a way to connect Salesforce to external APIs without using code. Then, we’ll run an email validation from Salesforce. We’ll do this with the following steps:

1. Create a Named Credential for the Mailgun API on Salesforce.

2. Set up External Services on the Salesforce platform.

3. Create a Screen Flow to use the Mailgun email validation API in Salesforce.

4. Run an email validation from Salesforce.

Let’s go over these steps in more detail. Keep in mind, you’ll need a Mailgun account with a plan that includes our Mailgun Optimize email validation functionality.

1. How do I create a Named Credential?

We’ll start by creating a Named Credential. To do so:

1. On the Salesforce platform, go to Setup > Named Credentials.

2. Click the New button to create a new Named Credential.

3. Specify the following values:

• Label = Mailgun Email Address Verifications

• Name = Mailgun_Email_Verification_API

• Certificate = leave blank

• Identity Type = Named Principal

• Authentication Protocol = Password Authentication

• Username = api

• Password = Your private API Key from your Mailgun account.

• Generate Authorization Header = true

4. Click Save.

2. How do I register an External Service?

Now, let’s use External Services on the Salesforce platform to integrate the Mailgun API. We’ll do so with the following steps:

1. In Salesforce, go to Setup > External Services.

2. Select New External Service.

3. Select From API Specification, and click Next

4. Specify these values for the following fields:

• External Service Name = MailgunEmailVerificationsExternalService 

• Select a Named Credential = the name of the Named Credential you created above (Mailgun Email Address Verifications in this example)

• Description = Mailgun's Email Address verification service

• Change the radio button to “Service Schema Complete JSON” and enter the following Swagger Schema:

Your External Service should look similar to this:

5. Select operation getv4AddressValidate and click Next.

6. Click Done.

3. How do I create a flow to use the external service?

Now that we’ve superpowered Salesforce with Mailgun, we’ll create a Screen Flow to use the Mailgun email validation API in Salesforce.

1. In Salesforce Setup, go to Flows > New Flow.

2. Select Screen Flow and click Create.

3. The flow will simply be three elements: a screen element, an action element, and another screen element

4. Add the first screen element:

The element name can be Email Address Entry and this element will only have one Text type field on it. Call this field “Email Address,” as shown below.

5. Add an action element below the screen element. In the flow, create a new resource by clicking the New Resource button. Add these field values to the new resource and save it:

• Resource Type = Variable

• API Name = Mailgun External Service

• Data Type = Apex-Defined

• Apex Class = ExternalService__MailgunEmailVerificationsExternalService_validationResponse (or whatever you called your external service in step 3 above)

• Available for input and available for output should both be set to True

6. Add an action element to the flow where the Type is External Service. The Action field should be your external service, and the input values just need to be the Email Address from screen element 1 above. Make sure you select Advanced > outputs and enter the apex defined variable you created above called MailgunExternalServices. Your action element should look like this:

7. Now add your final screen element. This will only have a Display Text type field on it, and it will output the result of the action from the external service call above.  The screen should look like this (note that the output value {!MailgunExternalService.result} can be found above the display text by clicking Insert a Resource and then selecting the output of your external service variable as shown below:

That’s all! Now let’s see it in action.

4. How do I run an email verification from Salesforce?

You’ve successfully integrated the Mailgun API into your Salesforce organization. Let’s see how it all works.

To test the flow you created above:

1. Click the Run button on the flow.

2. Then, click Enter any email address.

3. Enter an email address.

4. Click Next.

You should get a result from the Mailgun API that indicates if the email address you input is a deliverable or undeliverable email address. Want to learn more? Watch this video to see what this flow looks like in use.

Wrapping up

We’ve gone over some methods to verify your email address with our user interface and our Mailgun email validations API. We’ve also given you tips to integrate our API with external clients like Salesforce.

Now, you should be well on your way to checking your email addresses’ validity in real-time and get sending! Still have questions? Don’t hesitate to reach out!