Truemail server - lightweight rack based web API wrapper for Truemail gem. Verify email via Regex, DNS, SMTP and even more. Be sure that email address valid and exists.

Actual and maintainable documentation 📚 for developers is living here.

Table of Contents

• Features
• Installation
• Usage
  • Simple configuration example
  • Advanced configuration example
  • Request/response example
    • Existent email
    • Nonexistent email
    • Version
    • Healthcheck
• Truemail family
• Contributing
• License
• Code of Conduct
• Credits
• Versioning
• Changelog

Features

• Application configuration through environment vars
• One endpoint for email validation with token-based authentication
• No DB usage

Installation

git clone https://github.com/truemail-rb/truemail-rack.git

Usage

Before run application you must configure it first. List of available env vars names and values:

Var name	Value example	Required	Description
VERIFIER_EMAIL	your_email@example.com	+	Must be an existing email on behalf of which verification will be performed.
ACCESS_TOKENS	some_token	+	These tokens will be used for token-based authentication. Accepts one ore more values separated by commas.
VERIFIER_DOMAIN	somedomain.com	-	Must be an existing domain on behalf of which verification will be performed. By default verifier domain based on verifier email.
EMAIL_PATTERN	/regex_pattern/	-	You can override default Truemail regex pattern.
SMTP_ERROR_BODY_PATTERN	/regex_pattern/	-	You can override default Truemail regex pattern.
CONNECTION_TIMEOUT	1	-	Connection timeout is equal to 2 ms by default.
RESPONSE_TIMEOUT	1	-	A SMTP server response timeout is equal to 2 ms by default.
CONNECTION_ATTEMPTS	3	-	Total of connection attempts. It is equal to 2 by default. This parameter uses in mx lookup timeout error and smtp request (for cases when there is one mx server).
DEFAULT_VALIDATION_TYPE	mx	-	You can predefine Truemail default validation type (smtp). Available validation types: regex, mx, mx_blacklist, smtp.
VALIDATION_TYPE_FOR	somedomain.com:regex	-	You can predefine which type of validation will be used for domains. Available validation types: regex, mx, mx_blacklist, smtp. This configuration will be used over DEFAULT_VALIDATION_TYPE. All of validations for somedomain.com will be processed with regex validation only. Accepts one or more key:value separated by commas.
WHITELISTED_EMAILS	user@somedomain1.com	-	Validation of email which contains whitelisted email always will return true. Other validations will not processed even if it was defined in VALIDATION_TYPE_FOR. Accepts one ore more values separated by commas.
BLACKLISTED_EMAILS	user@somedomain2.com	-	Validation of email which contains blacklisted email always will return false. Other validations will not processed even if it was defined in VALIDATION_TYPE_FOR. Accepts one ore more values separated by commas.
WHITELISTED_DOMAINS	somedomain1.com	-	Validation of email which contains whitelisted domain always will return true. Other validations will not processed even if it was defined in VALIDATION_TYPE_FOR. Accepts one ore more values separated by commas.
BLACKLISTED_DOMAINS	somedomain2.com	-	Validation of email which contains blacklisted domain always will return false. Other validations will not processed even if it was defined in VALIDATION_TYPE_FOR. Accepts one ore more values separated by commas.
WHITELIST_VALIDATION	true	-	With this option Truemail will validate email which contains whitelisted domain only, i.e. if domain whitelisted, validation will passed to Regex, MX or SMTP validators. Validation of email which not contains whitelisted domain always will return false. It is equal false by default.
BLACKLISTED_MX_IP_ADDRESSES	127.0.1.1,127.0.1.2	-	With this option Truemail will filter out unwanted mx servers via predefined list of ip addresses. It can be used as a part of DEA (disposable email address) validations. Accepts one ore more values separated by commas.
DNS	8.8.8.8,8.8.4.4:53	-	This option will provide to use custom DNS gateway when Truemail interacts with DNS. If you won't specify nameserver's ports Truemail will use default DNS TCP/UDP port 53. Accepts one ore more values separated by commas. By default Truemail uses DNS gateway from system settings.
NOT_RFC_MX_LOOKUP_FLOW	true	-	This option will provide to use not RFC MX lookup flow. It means that MX and Null MX records will be checked on the DNS validation layer only. By default this option is disabled.
SMTP_PORT	2525	-	SMTP port number. It is equal to 25 by default.
SMTP_FAIL_FAST	true	-	This option will provide to use SMTP fail fast behavior. When smtp_fail_fast is enabled it means that Truemail ends smtp validation session after first attempt on the first mx server in any fail cases (network connection/timeout error, smtp validation error). By default this option is disabled, available for SMTP validation only.
SMTP_SAFE_CHECK	true	-	This option will be parse bodies of SMTP errors. It will be helpful if SMTP server does not return an exact answer that the email does not exist. By default this option is disabled, available for SMTP validation only.
LOG_STDOUT	true	-	This option will be enable log all http requests to stdout. By default this option is disabled.

Run Truemail server with command as in example below:

Simple configuration example

VERIFIER_EMAIL=your_email@example.com ACCESS_TOKENS=a262d915-15bc-417c-afeb-842c63b54154 rackup

# =>
# Thin web server (v1.8.1 codename Infinite Smoothie)
# Maximum connections set to 1024
# Listening on localhost:9292, CTRL+C to stop

Advanced configuration example

VERIFIER_EMAIL=your_email@example.com \
ACCESS_TOKENS=a262d915-15bc-417c-afeb-842c63b54154,f44cd67e-aaa0-4e6c-aa6c-d52cf61f84ac \
EMAIL_PATTERN="/\A.+@.+\z/" \
SMTP_ERROR_BODY_PATTERN="/(?=.*550)(?=.*(user|account|customer|mailbox|something_else)).*/" \
VALIDATION_TYPE_FOR=somedomain1.com:regex,somedomain2.com:mx \
WHITELISTED_EMAILS=whitelisted@example.com \
BLACKLISTED_EMAILS=blacklisted1@example.com,blacklisted2@example.com \
WHITELISTED_DOMAINS=somedomain3.com \
BLACKLISTED_DOMAINS=somedomain4.com,somedomain5.com \
WHITELIST_VALIDATION=true \
BLACKLISTED_MX_IP_ADDRESSES=127.0.1.1,127.0.1.2 \
DNS=8.8.8.8,8.8.4.4:53 \
NOT_RFC_MX_LOOKUP_FLOW=true \
SMTP_PORT=2525 \
SMTP_FAIL_FAST=true \
SMTP_SAFE_CHECK=true \
LOG_STDOUT=true \
thin -R config.ru -a 0.0.0.0 -p 9292 -e production start

# =>
# Thin web server (v1.8.1 codename Infinite Smoothie)
# Maximum connections set to 1024
# Listening on localhost:9292, CTRL+C to stop
# 127.0.0.1 - - [26/Feb/2020:16:41:13 +0200] "GET /?email=admin%40bestweb.com.ua HTTP/1.1" 200 - 0.9195

Request/response example

Existent email

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: a262d915-15bc-417c-afeb-842c63b54154" http://localhost:9292?email=admin@bestweb.com.ua

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 410
Connection: keep-alive
Server: thin

{
  "date": "2021-02-07 10:00:56 +0200",
  "email": "admin@bestweb.com.ua",
  "validation_type": "smtp",
  "success": true,
  "errors": null,
  "smtp_debug": null,
  "configuration": {
    "validation_type_by_domain": null,
    "whitelisted_emails": null,
    "blacklisted_emails": null,
    "whitelisted_domains": null,
    "blacklisted_domains": null,
    "whitelist_validation": false,
    "blacklisted_mx_ip_addresses": null,
    "dns": null,
    "email_pattern": "default gem value",
    "not_rfc_mx_lookup_flow": false,
    "smtp_error_body_pattern": "default gem value",
    "smtp_fail_fast": false,
    "smtp_safe_check": false
  }
}

Nonexistent email

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: a262d915-15bc-417c-afeb-842c63b54154" http://localhost:9292?email=ololo@bestweb.com.ua

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 541
Connection: keep-alive
Server: thin

{
  "date": "2021-02-07 10:10:42 +0200",
  "email": "ololo@bestweb.com.ua",
  "validation_type": "smtp",
  "success": false,
  "errors": {
    "smtp": "smtp error"
  },
  "smtp_debug": [
    {
      "connection": true,
      "errors": {
        "rcptto": "550 5.7.1 No such user!\n"
      },
      "mail_host": "213.180.204.89",
      "port_opened": true
    }
  ],
  "configuration": {
    "validation_type_by_domain": null,
    "whitelisted_emails": null,
    "blacklisted_emails": null,
    "whitelisted_domains": null,
    "blacklisted_domains": null,
    "whitelist_validation": false,
    "blacklisted_mx_ip_addresses": null,
    "dns": null,
    "email_pattern": "default gem value",
    "not_rfc_mx_lookup_flow": false,
    "smtp_error_body_pattern": "default gem value",
    "smtp_fail_fast": false,
    "smtp_safe_check": false
  }
}

Version

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: a262d915-15bc-417c-afeb-842c63b54154" http://localhost:9292/version

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 108
Content-Type: application/json
Server: thin

{
  "core": "3.3.0",
  "platform": "ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin22]",
  "version": "0.10.0"
}

Healthcheck

curl -i http://localhost:9292/healthcheck

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Server: thin

Truemail family

All Truemail solutions: https://truemail-rb.org

Name	Type	Description
truemail	ruby gem	Configurable framework agnostic plain Ruby email validator, main core
truemail-go	go package	Configurable Golang email validator, main core
truemail-rack-docker	docker image	Lightweight rack based web API dockerized image 🐳 of Truemail server
truemail-ruby-client	ruby gem	Truemail web API client library for Ruby
truemail-crystal-client	crystal shard	Truemail web API client library for Crystal
truemail-java-client	java lib	Truemail web API client library for Java
truemail-rspec	ruby gem	Truemail configuration and validator RSpec helpers

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/truemail-rb/truemail-rack. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. Please check the open tickets. Be sure to follow Contributor Code of Conduct below and our Contributing Guidelines.

License

This application is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Truemail project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Credits

• The Contributors for code and awesome suggestions
• The Stargazers for showing their support

Versioning

truemail-rack uses Semantic Versioning 2.0.0