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
- Installation
- Usage
- Truemail family
- Contributing
- License
- Code of Conduct
- Credits
- Versioning
- Changelog
- Application configuration through environment vars
- One endpoint for email validation with token-based authentication
- No DB usage
git clone https://github.com/truemail-rb/truemail-rack.gitBefore run application you must configure it first. List of available env vars names and values:
| Var name | Value example | Required | Description |
|---|---|---|---|
VERIFIER_EMAIL |
[email protected] |
+ | 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 |
[email protected] |
- | 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 |
[email protected] |
- | 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:
[email protected] 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[email protected] \
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 \
[email protected] \
[email protected],[email protected] \
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.9195curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: a262d915-15bc-417c-afeb-842c63b54154" http://localhost:9292?[email protected]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": "[email protected]",
"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
}
}curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: a262d915-15bc-417c-afeb-842c63b54154" http://localhost:9292?[email protected]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": "[email protected]",
"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
}
}curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: a262d915-15bc-417c-afeb-842c63b54154" http://localhost:9292/versionHTTP/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"
}curl -i http://localhost:9292/healthcheckHTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Server: thinAll 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 |
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.
This application is available as open source under the terms of the MIT License.
Everyone interacting in the Truemail project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
- The Contributors for code and awesome suggestions
- The Stargazers for showing their support
truemail-rack uses Semantic Versioning 2.0.0
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent