Skip to content

Truemail server. Lightweight rack based web API πŸš€

License

Notifications You must be signed in to change notification settings

truemail-rb/truemail-rack

Repository files navigation

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 πŸ“š for developers is living here.

Table of Contents

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

Versioning

truemail-rack uses Semantic Versioning 2.0.0