Home

Awesome

Truemail server - lightweight rack based web API

Maintainability Test Coverage CircleCI GitHub release (latest by date) Gitter GitHub Contributor Covenant

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 :books: for developers is living here.

Table of Contents

Features

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 nameValue exampleRequiredDescription
VERIFIER_EMAILyour_email@example.com+Must be an existing email on behalf of which verification will be performed.
ACCESS_TOKENSsome_token+These tokens will be used for token-based authentication. Accepts one ore more values separated by commas.
VERIFIER_DOMAINsomedomain.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_TIMEOUT1-Connection timeout is equal to 2 ms by default.
RESPONSE_TIMEOUT1-A SMTP server response timeout is equal to 2 ms by default.
CONNECTION_ATTEMPTS3-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_TYPEmx-You can predefine Truemail default validation type (smtp). Available validation types: regex, mx, mx_blacklist, smtp.
VALIDATION_TYPE_FORsomedomain.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_EMAILSuser@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_EMAILSuser@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_DOMAINSsomedomain1.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_DOMAINSsomedomain2.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_VALIDATIONtrue-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_ADDRESSES127.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.
DNS8.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_FLOWtrue-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_PORT2525-SMTP port number. It is equal to 25 by default.
SMTP_FAIL_FASTtrue-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_CHECKtrue-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_STDOUTtrue-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

NameTypeDescription
truemailruby gemConfigurable framework agnostic plain Ruby email validator, main core
truemail-gogo packageConfigurable Golang email validator, main core
truemail-rack-dockerdocker imageLightweight rack based web API dockerized image :whale: of Truemail server
truemail-ruby-clientruby gemTruemail web API client library for Ruby
truemail-crystal-clientcrystal shardTruemail web API client library for Crystal
truemail-java-clientjava libTruemail web API client library for Java
truemail-rspecruby gemTruemail 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

Versioning

truemail-rack uses Semantic Versioning 2.0.0