This SDK library integrates with Verifalia and allows to verify email addresses in Ruby 2.6.0 or higher.
Verifalia is an online service that provides email verification and mailing list cleaning; it helps businesses reduce their bounce rate, protect their sender reputation, and ensure their email campaigns reach the intended recipients. Verifalia can verify email addresses in real-time or in bulk, using its API or client area; it also offers various features and settings to customize the verification process according to the user’s needs.
Verifalia's email verification process consists of several steps, each taking fractions of a second: it checks the formatting and syntax (RFC 1123, RFC 2821, RFC 2822, RFC 3490, RFC 3696, RFC 4291, RFC 5321, RFC 5322, and RFC 5336) of each email address, the domain and DNS records, the mail exchangers, and the mailbox existence, with support for internationalized domains and mailboxes. It also detects risky email types, such as catch-all, disposable, or spam traps / honeypots.
Verifalia provides detailed and accurate reports for each email verification: it categorizes each email address as Deliverable,
Undeliverable, Risky, or Unknown, and assigns one of its exclusive set of over 40 status codes.
It also explains the undeliverability reason and provides comprehensive verification details. The service allows the user to choose the desired
quality level, the waiting timeout, the deduplication preferences, the data retention settings, and the callback preferences
for each verification.
Of course, Verifalia never sends emails to the contacts or shares the user's data with anyone.
To learn more about Verifalia please see https://verifalia.com
- Adding Verifalia to your Ruby app
- Verifying email addresses
- Managing credits
- Changelog / What's new
Easily include Verifalia in your Ruby application using Bundler; just add the following line to your Gemfile to get the latest version:
gem 'verifalia'To manually install verifalia via Rubygems simply run gem install:
gem install verifaliaFirst things first: authentication to the Verifalia API is performed by way of either the credentials of your root Verifalia account or of one of its users (previously known as sub-accounts): if you don't have a Verifalia account, just register for a free one. For security reasons, it is always advisable to create and use a dedicated user for accessing the API, as doing so will allow to assign only the specific needed permissions to it.
Learn more about authenticating to the Verifalia API at https://verifalia.com/developers#authentication
The most straightforward method for authenticating against the Verifalia API involves using a username and password pair.
These credentials can be applied during the creation of a new instance of the Verifalia::Client class, serving as the
initial step for all interactions with the Verifalia API: the provided username and password will be automatically
transmitted to the API using the HTTP Basic Auth method.
require 'verifalia'
# ...
verifalia = Verifalia::Client.new username: 'your-username', password: 'your-password'In addition to the HTTP Basic Auth method, this SDK also supports using a cryptographic X.509 client certificate to authenticate against the Verifalia API, through the TLS protocol. This method, also called mutual TLS authentication (mTLS) or two-way authentication, offers the highest degree of security, as only a cryptographically-derived key (and not the actual credentials) is sent over the wire on each request.
# my-cert.pem contains both the private and public (certificate) key, but
# you may specify different files if needed.
verifalia = Verifalia::Client.new ssl_client_cert: './my-cert.pem',
ssl_client_key: './my-cert.pem'See how to create a self-signed X.509 client certificate for TLS mutual authentication on the Verifalia website, for more information on creating your own certificates for the Verifalia API.
Every operation related to verifying / validating email addresses is performed through the
email_validations attribute exposed by the Verifalia::Client instance you created above, which
exposes some useful methods: in the next few paragraphs we are looking at the most used ones, so
it is strongly advisable to explore the library and look at the embedded help for other opportunities.
The library automatically waits for the completion of email verification jobs: if needed, it is possible to adjust the wait options and have more control over the entire underlying polling process. Please refer to the Wait options section below for additional details.
To validate an email address from a Ruby application you can invoke the submit() method: it
accepts one or more email addresses and any eventual verification options you wish to pass to Verifalia,
including the expected results quality, deduplication preferences, processing priority.
In the following example, we check an email address with this library, using the default options:
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit 'batman@gmail.com'
# At this point the address has been validated: let's print its validation
# result to the console.
entry = job.entries[0]
puts "Classification: #{entry.classification} (status: #{entry.status})"
# Classification: Deliverable (status: Success)As you may expect, each entry may include various additional details about the verified email address:
| Attribute | Description |
|---|---|
ascii_email_address_domain_part |
Gets the domain part of the email address, converted to ASCII if needed and with comments and folding white spaces stripped off. |
classification |
A string with the classification for this entry; see Verifalia::EmailValidations::EntryClassification for a list of the values supported at the time this SDK has been released. |
completed_on |
The date this entry has been completed, if available. |
custom |
A custom, optional string which is passed back upon completing the validation. To pass back and forth a custom value, use the custom attribute of Verifalia::EmailValidations::RequestEntry. |
duplicate_of |
The zero-based index of the first occurrence of this email address in the parent Job, in the event the status for this entry is Duplicate; duplicated items do not expose any result detail apart from this and the eventual custom values. |
index |
The index of this entry within its Job container; this property is mostly useful in the event the API returns a filtered view of the items. |
input_data |
The input string being validated. |
email_address |
Gets the email address, without any eventual comment or folding white space. Returns null if the input data is not a syntactically invalid e-mail address. |
email_address_domain_part |
Gets the domain part of the email address, without comments and folding white spaces. |
email_address_local_part |
Gets the local part of the email address, without comments and folding white spaces. |
has_international_domain_name |
If true, the email address has an international domain name. |
has_international_mailbox_name |
If true, the email address has an international mailbox name. |
is_disposable_email_address |
If true, the email address comes from a disposable email address (DEA) provider. What is a disposable email address? |
is_free_email_address |
If true, the email address comes from a free email address provider (e.g. gmail, yahoo, outlook / hotmail, ...). |
is_role_account |
If true, the local part of the email address is a well-known role account. |
status |
The status for this entry; see Verifalia::EmailValidations::EntryStatus for a list of the values supported at the time this SDK has been released. |
suggestions |
The potential corrections for the input data, in the event Verifalia identified potential typos during the verification process. |
syntax_failure_index |
The position of the character in the email address that eventually caused the syntax validation to fail. |
Here is another example, showing some of the additional result details provided by Verifalia:
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit 'bat[man@gmal.com'
entry = job.entries[0]
puts "Classification: #{entry.classification}"
puts "Status: #{entry.status}"
puts "Syntax failure index: #{entry.syntax_failure_index}"
puts "Suggestions:"
entry.suggestions.each do |suggestion|
puts "- #{suggestion}"
end
# Classification: Undeliverable
# Status: InvalidCharacterInSequence
# Syntax failure index: 3
# Suggestions:
# - batman@gmail.comTo check a list of email addresses - instead of a single address - it is possible to pass an array of strings with the
emails to verify to the submit() method; here is an example showing how to validate an array with some
email addresses:
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit ['batman@gmail.com', 'samantha42@yahoo.it']
job.entries.each do |entry|
puts "#{entry.input_data} => #{entry.classification} (#{entry.status})"
end
# batman@gmail.com => Deliverable (Success)
# samantha42@yahoo.it => Deliverable (Success)While submitting one or more email addresses for verification, it is possible to specify several options which affect the behavior of the Verifalia processing engine as well as the verification flow from the API consumer standpoint.
Verifalia offers three distinct quality levels - namely, Standard, High and Extreme - which rule out how the email verification engine should
deal with temporary undeliverability issues, with slower mail exchangers and other potentially transient
problems which can affect the quality of the verification results. The submit() method accepts a quality keyword
argument which allows
to specify the desired quality level; here is an example showing how to verify an email address using
the High quality level:
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit 'batman@gmail.com', quality: 'High'While accepting multiple email addresses at once, the submit() method allows to specify how to
deal with duplicated entries pertaining to the same input set; Verifalia supports a Safe deduplication
mode, which strongly adheres to the old IETF standards, and a Relaxed mode which is more in line with
what can be found in the majority of today's mail exchangers configurations.
In the next example, we show how to import and verify a list of email addresses and mark duplicated entries using the Relaxed deduplication mode:
emails = [
'batman@gmail.com',
'steve.vai@best.music',
'samantha42@yahoo.it'
]
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit entries, deduplication: 'Relaxed'Verifalia automatically deletes completed email verification jobs according to the data retention policy defined at the account level, which can be eventually overridden at the user level: one can use the Verifalia clients area to configure these settings.
It is also possible to specify a per-job data retention policy which govern the time to live of a submitted
email verification job; to do that, provide the submit() method with the keyword argument retention
set according to the dd.hh:MM:ss format, with the dd. part being optional.
Here is how, for instance, one can set a data retention policy of 10 minutes while verifying an email address:
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit 'batman@gmail.com', retention: '0:10:0'By default, the submit() method submits an email verification job to Verifalia and waits
for its completion; the entire process may require some time to complete depending on the plan of the
Verifalia account, the number of email addresses the submission contains, the specified quality level
and other network factors including the latency of the mail exchangers under test.
In waiting for the completion of a given email verification job, the library automatically polls the underlying Verifalia API until the results are ready; by default, it tries to take advantage of the long polling mode introduced with the Verifalia API v2.4, which allows to minimize the number of requests and get the verification results faster.
In certain scenarios (in a microservice architecture, for example), however, it may preferable to avoid
waiting for a job completion and ask the Verifalia API, instead, to just queue it: in that case, the library
would just return the job overview (and not its verification results) and it will be necessary to retrieve
the verification results using the get() method.
To do that, it is possible to specify the Verifalia::EmailValidations::WaitOptions.no_wait as the value
for the wait_options keyword argument of the submit() method, as shown in the next example:
wait_options = Verifalia::EmailValidations::WaitOptions.no_wait
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit 'elon.musk@tesla.com', wait_options: wait_options
puts "Status: #{job.overview.status}"
# Status: InProgressFor jobs with a large number of email addresses, it could be useful to track progress as they are processed
by the Verifalia email verification engine; to do that, it is possible to create an instance of the
Verifalia::EmailValidations::WaitOptions class and provide a lambda which eventually receives progress notifications through the
progress attribute.
Here is how to define a progress notification handler which displays the progress percentage of a submitted job to the console window:
progress = ->(overview) do
puts "Progress: #{(overview.progress&.percentage || 0) * 100}%..."
end
wait_options = Verifalia::EmailValidations::WaitOptions.new 30 * 1000, 30 * 1000,
progress: progress
emails = [
'alice@example.com',
'bob@example.net',
'charlie@example.org'
]
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.submit emails, wait_options: wait_optionsAlong with each email validation job, it is possible to specify an URL which Verifalia will invoke (POST) once the job completes: this URL must use the HTTPS or HTTP scheme and be publicly accessible over the Internet. To learn more about completion callbacks, please see https://verifalia.com/developers#email-validations-completion-callback
To specify a completion callback URL, specify the completion_callback keyword argument while
invoking the submit() method, as shown in the example below:
# verifalia = Verifalia::Client.new ...
verifalia.email_validations.submit 'batman@gmail.com',
completion_callback: {
'url' => 'https://your-website-here/foo/bar'
}Note that completion callbacks are invoked asynchronously and it could take up to several seconds for your callback URL to get invoked.
It is possible to retrieve a job through the get() method, which
returns, respectively, a Verifalia::EmailValidations::Job instance for the desired
email verification job. While doing that, the library automatically waits for the completion of
the job, and it is possible to adjust this behavior by passing to the aforementioned method
a wait_options keyword argument, in the exactly same fashion as described for the submit() method;
please see the Wait options section for additional details.
Here is an example showing how to retrieve a job, given its identifier:
# verifalia = Verifalia::Client.new ...
job = verifalia.email_validations.get 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'This library also allows to export the entries of a completed email validation
job in different output formats through the export() method, with the goal of
generating a human-readable representation of the verification results.
WARNING: While the output schema (columns / labels / data format) is fairly complete, you should always consider it as subject to change: use the
get()method instead if you need to rely on a stable output schema.
Here is an example showing how to export a given email verification job as an Excel (.xslx) file:
# verifalia = Verifalia::Client.new ...
data = verifalia.email_validations.export 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea',
Verifalia::EmailValidations::ExportedEntriesFormat::EXCEL_XLSX
File.open('./export.xlsx', 'wb') do |fp|
fp.write(data)
endVerifalia automatically deletes completed jobs after a configurable
data-retention policy (see the related section) but it is strongly advisable that
you delete your completed jobs as soon as possible, for privacy and security reasons.
To do that, you can invoke the delete() method passing the job Id you wish to get rid of:
# verifalia = Verifalia::Client.new ...
verifalia.email_validations.delete 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'Once deleted, a job is gone and there is no way to retrieve its email validation results.
To manage the Verifalia credits for your account you can use the credits attribute exposed
by the Verifalia::Client instance created above. Like for the previous topic, in the next
few paragraphs we are looking at the most used operations, so it is strongly advisable to
explore the library and look at the embedded documentation for other opportunities.
One of the most common tasks you may need to perform on your account is retrieving the available
number of free daily credits and credit packs. To do that, you can use the get_balance() method,
which returns a Verifalia::Credits::Balance object, as shown in the next example:
# verifalia = Verifalia::Client.new ...
balance = verifalia.credits.get_balance
puts "Credit packs: #{balance.credit_packs}"
puts "Free daily credits: #{balance.free_credits} (will reset in #{balance.free_credits_reset_in})"
# Credit packs: 956.332
# Free daily credits: 128.66 (will reset in 09:08:23)To add credit packs to your Verifalia account visit https://verifalia.com/client-area#/credits/add.
This section lists the changelog for the current major version of the library: for older versions, please see the project releases.
Released on January 18th, 2024
- Added support for API v2.5
- Added support for classification overrides
- Added support for AI-powered suggestions
- Added
EntryClassification,EntryStatus,ExportedEntriesFormatandJobStatusmodule constants - Improved documentation
Released on March 12th, 2023
- Added support for API v2.4
- Added support for new completion callback options
- Added support for specifying a custom wait time while submitting and retrieving email verification jobs
- Added support for exporting completed email verification jobs in different output formats (CSV, Excel, Excel 97-2003)
- Breaking change: the default job submission and retrieval behavior is now to wait for the completion
of jobs (but it is possible to change that through the new
WaitOptionsclass) - Bumped dependencies
- Improved documentation