GitHub - truemail-rb/truemail-rack: Truemail server. Lightweight rack based web API 🚀

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.

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

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.circleci		.circleci
.github		.github
app/truemail_server		app/truemail_server
config		config
spec		spec
.codeclimate.yml		.codeclimate.yml
.gitignore		.gitignore
.reek.yml		.reek.yml
.rspec		.rspec
.ruby-gemset		.ruby-gemset
.ruby-version		.ruby-version
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE.txt		LICENSE.txt
README.md		README.md
config.ru		config.ru

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

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

About

Releases 34

Sponsor this project

Contributors 2

Languages

License

truemail-rb/truemail-rack

Folders and files

Latest commit

History

Repository files navigation

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

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 34

Sponsor this project

Contributors 2

Languages