truemail: layered email validation in plain Ruby
🚀 Configurable framework agnostic plain Ruby 📨 email validator/verifier. Verify email via Regex, DNS, SMTP and even more. Be sure that email address valid and exists.
At a glance
- What is it?
- truemail is a framework agnostic Ruby gem that checks an address in three separate layers, syntax by regex, the domain by DNS MX records and the mailbox by an SMTP exchange, with whitelist, disposable address, host audit and event logging features on top.
- Who is it for?
- truemail fits a Ruby application that needs to know more than whether an address is well formed, especially one that already runs an SMTP conversation with its users and therefore has a verifier identity it can use. It is the wrong dependency for a project that only needs a syntax check, and it is the wrong one for a team unwilling to maintain a verifier mailbox and an outbound SMTP path.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Three layers that can be enabled separately
The gem's premise is that email validation is not one operation but several, and that a project should be able to pay for only the ones it needs. The README splits them into syntax checking, mail server existence check and mail existence check.
Syntax checking verifies the address against a regex pattern. The mail server existence check looks at DNS records to see whether the domain can accept mail. The mail existence check is the expensive one: it opens an SMTP connection and emulates an email sending conversation to find out whether the mailbox really exists and can receive mail.
The description lists the headline features and they follow from that design. The validator is configurable so that you validate only what you need, internationalized email addresses are supported, there are whitelist and blacklist validation layers, different MX and SMTP validation flows can be configured, disposable email address validation can be enabled, and there is a simple SMTP debugger. There is also an event logger, JSON serializers, and host auditor tools that help detect common host problems interfering with proper email verification. The library can also be used as an independent stateless microservice, Truemail Server.
The audience is a Ruby application that treats signup or contact forms as a business problem worth solving properly, and the framework agnostic framing means it is not tied to Rails, Sinatra or any other web framework.
Global configuration or an independent one per call
The configuration surface is wide and deliberately explicit. The README lists the available options in full: verifier email, verifier domain, email pattern, SMTP error body pattern, connection timeout, response timeout, connection attempts, default validation type, validation type for domains, whitelisted emails, blacklisted emails, whitelisted domains, blacklisted domains, whitelist validation, blacklisted MX IP addresses, custom DNS gateways, RFC MX lookup flow, SMTP port number, SMTP fail fast, SMTP safe check, event logger and JSON serializer.
The reason so much of it is exposed is that email verification is a cost and a risk decision, and both are per deployment. A signup form in a consumer product may run the full SMTP exchange, while a form that only needs to catch typos stops after the regex. The default validation type and the validation type for domains let you express that split, for example running one flow for known domains and a stricter one elsewhere.
The verifier email and verifier domain are the core of the SMTP layer. The README states that the verifier email is a required parameter and must be an existing email on behalf of which verification will be performed, and that the verifier domain is optional, defaulting to a domain derived from the verifier email. That requirement has consequences. It means the deploying team must run a mailbox it controls, that mailbox must be deliverable, and the SMTP conversation is performed on its behalf.
There are two ways to hold this configuration. You can set a global configuration through the Truemail.configure block, or you can use a custom independent configuration for a particular call, which is the option for a multi tenant application where different customers need different rules.
Adding the gem and setting a verifier identity
Installation is a Gemfile line followed by a bundle:
gem 'truemail'bundleor a direct install without a Gemfile:
gem install truemailThe requirement is Ruby MRI 2.5.0 or later.
The first use is the configuration block. Requiring the gem and opening the configure block is what gives you access to Truemail.configuration and the configuration features:
require 'truemail'
Truemail.configure do |config|
# Required parameter. Must be an existing email on behalf of which verification will be performed
config.verifier_email = '[email protected]'
# Optional parameter. Must be an existing domain on behalf of which verification will be performed.
# By default verifier domain based on verifier email
config.verifier_domain = 'somedomain.com'
# Optional parameter. You can override default regex pattern
config.email_pattern = /regex_pattern/
# Optional parameter. You can override default regex pattern
config.smtp_error_body_pattern = /regex_pattern/The two regex overrides are worth understanding separately. The email pattern is the syntax check, and the SMTP error body pattern is what the gem matches against the server's response to decide whether the failure means the mailbox is absent or merely busy. A busy mailbox and a nonexistent mailbox often produce different server responses, and that difference is what the second pattern is for.
The documentation is published separately from the README, at truemail-rb.org/truemail-gem, and the README points there for the full option reference, the whitelist and blacklist syntax, the MX lookup flows and the auditing tools.
Whitelist, blacklist and disposable address decisions
Three of the configuration options shape the result before any network traffic happens, and the README gives each its own section.
The whitelist and blacklist layers work on both individual addresses and on domains, with separate options for whitelisted emails, blacklisted emails, whitelisted domains and blacklisted domains. There is also a whitelist validation switch, which is what makes the whitelist a bypass rather than merely a preference. The README documents a whitelist case, a whitelist validation case, a blacklist case and a duplication case, which suggests the layers are applied in a defined order and that the same address can arrive through more than one of them.
The disposable email address validation is a separate flow rather than a list you maintain, and it is toggled through the DEA validation flow option. That is a meaningfully different approach from the blacklist, because the disposable domain list changes constantly and keeping your own copy current is work nobody wants.
The blacklist also extends to the infrastructure side, with an option for blacklisted MX IP addresses, and there is support for custom DNS gateways, which is the hook for environments where the resolver is not the system default, such as a container with its own resolver configuration.
The practical point for an engineer evaluating this gem is that these are not cosmetic options. Each one changes what your application accepts, and the combination you choose is effectively your email policy, expressed in configuration rather than in application code.
Host audit catches the reasons verification fails
A surprising share of failed verifications are not about the address at all. They come from the host running the verification. The gem addresses this with a host auditor, and the README breaks it into three audits: an IP audit, a DNS audit and a PTR audit.
The IP audit looks at the address the host is connecting from, which matters because a mail server may refuse or behave differently depending on where the connection originates. The DNS audit checks that the host can resolve what it needs to, and the PTR audit checks the reverse DNS record of the host address, which many receiving servers use as part of their filtering.
The reason this belongs in the library rather than in a runbook is that a verifier that suddenly starts failing across the board is usually an outbound network or DNS problem on the sending side, and the same tools that perform the audit can tell you whether the host is the problem before you start blaming the domain you were checking.
The README lists a section on the auditor alongside the validator in its table of contents, along with JSON serializers for both the auditor and the validator. That pairing is what makes the feature useful in a service context: the same objects that the library returns internally can be serialised for logging, for a support tool or for an HTTP response when the gem is running as the Truemail Server microservice.
Fail fast, safe check and the MX lookup flow decide the cost
Three options control the behaviour of the network part, and they are worth setting deliberately rather than leaving at defaults.
SMTP fail fast is listed as a configuration option, and the README has a dedicated section for the case where it is enabled. The idea is that when the server gives an immediate negative answer, the gem stops the conversation instead of completing it, which shortens the check when the answer is already known.
The SMTP safe check is the opposite concern, and the README documents it both disabled and enabled. Turning it on means the gem takes extra care in the SMTP exchange, which is what you want when a false positive would let a nonexistent address through, and what you do not want when you are verifying thousands of signups a minute.
The RFC MX lookup flow is the other switch, and the README has sections for the RFC flow and the flow that is not RFC, so you can select which lookup behaviour your verification follows. Custom DNS gateways belong here too, since an MX lookup is a DNS operation and the resolver your host uses is often not the resolver you want for this.
Add to that the timeouts, the connection attempts, the SMTP port number and the event logger, and the picture is complete: the gem gives you a lot of levers, all of which point the same way. Email verification is a network operation against servers you do not control, and the settings exist to bound both the time it takes and the mistakes it makes.
A release line that stopped in 2024 while the branch kept moving
The maintenance picture needs reading carefully. The recent releases are v3.3.1 on 2024-04-23, v3.3.0 on 2024-02-26 and v3.2.0 on 2024-02-24, so the newest published tag is more than two years old. The last push was on 2026-10-13, so the master branch is still receiving work, but it is not being cut into releases at anything like the same rate.
That is the kind of gap that decides an adoption. If you deploy from RubyGems, you are deploying code from April 2024, and the fixes that landed on master after that are not available to you without pointing at the git source. If you vendor from the branch, you are taking unreleased changes and a support commitment that nobody has made in writing. Neither is wrong, but you have to choose, and the README does not document a policy on which lines are supported.
The licence is MIT, with a LICENSE.txt at the top of the repository, and the project keeps a CHANGELOG.md, a CONTRIBUTING.md and a CODE_OF_CONDUCT.md. The repository also shows the usual signals of a gem with real usage: a Rakefile, a spec directory with an .rspec configuration, a CircleCI directory, a .reek.yml, a .codeclimate.yml and a rubygems release badge. The project is also listed in the awesome-ruby collection and carries a Truemail family of related projects, with the server version documented separately.
The home page for the gem is truemail-rb.org/truemail-gem, and the README is explicit that the actual and maintained documentation lives there rather than in the repository.
Editorial conclusion
truemail fits a Ruby application that needs to know more than whether an address is well formed, especially one that already runs an SMTP conversation with its users and therefore has a verifier identity it can use. It is the wrong dependency for a project that only needs a syntax check, and it is the wrong one for a team unwilling to maintain a verifier mailbox and an outbound SMTP path. Before you adopt it, decide which validation layers you will actually enforce, configure the verifier email and domain, and check the release line you pin, since the newest published tag is from 2024 while the branch has continued to receive pushes.
Frequently asked questions
What does the truemail gem do?
It validates an email address through three layers: a regex syntax check, a DNS MX record check for the domain, and an SMTP exchange that emulates sending mail to find out whether the mailbox exists. You configure which layers you want to run.
How do I install the truemail gem?
Add `gem 'truemail'` to the Gemfile and run bundle, or install it directly with `gem install truemail`. The requirement is Ruby MRI 2.5.0 or later.
What is the verifier email used for in truemail?
The README describes it as a required parameter that must be an existing email on behalf of which verification will be performed. The verifier domain is optional and defaults to a domain derived from the verifier email.
What do the truemail host audit tools check?
The auditor has three parts: an IP audit, a DNS audit and a PTR audit. They are meant to detect common host problems that interfere with proper email verification from your own server.
How do I configure truemail globally versus per call?
A global configuration is set through the Truemail.configure block, which is what gives access to Truemail.configuration. The README also documents a custom independent configuration for cases where you need a separate set of rules.
Official sources
Was this useful?