{"id":13879855,"url":"https://github.com/maximeg/email_inquire","last_synced_at":"2025-04-12T20:45:56.621Z","repository":{"id":56844536,"uuid":"69898926","full_name":"maximeg/email_inquire","owner":"maximeg","description":"Validate email for common typos and one-time email providers","archived":false,"fork":false,"pushed_at":"2023-09-01T14:12:23.000Z","size":151,"stargazers_count":259,"open_issues_count":6,"forks_count":25,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-04T00:09:38.162Z","etag":null,"topics":["email","rails","ruby","ruby-gem","validation"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximeg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-03T18:32:04.000Z","updated_at":"2024-12-17T14:11:49.000Z","dependencies_parsed_at":"2024-06-19T01:33:33.708Z","dependency_job_id":null,"html_url":"https://github.com/maximeg/email_inquire","commit_stats":{"total_commits":99,"total_committers":4,"mean_commits":24.75,"dds":"0.030303030303030276","last_synced_commit":"23196f6c96c2bd99493cfb6705712cd6ee8429ee"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximeg%2Femail_inquire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximeg%2Femail_inquire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximeg%2Femail_inquire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximeg%2Femail_inquire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximeg","download_url":"https://codeload.github.com/maximeg/email_inquire/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631692,"owners_count":21136559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","rails","ruby","ruby-gem","validation"],"created_at":"2024-08-06T08:02:36.086Z","updated_at":"2025-04-12T20:45:56.600Z","avatar_url":"https://github.com/maximeg.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# EmailInquire\n\n[![Gem Version](https://badge.fury.io/rb/email_inquire.svg)](https://badge.fury.io/rb/email_inquire) [![Build Status](https://travis-ci.org/maximeg/email_inquire.svg?branch=master)](https://travis-ci.org/maximeg/email_inquire) [![codecov](https://codecov.io/gh/maximeg/email_inquire/branch/master/graph/badge.svg)](https://codecov.io/gh/maximeg/email_inquire) [![Code Climate](https://codeclimate.com/github/maximeg/email_inquire/badges/gpa.svg)](https://codeclimate.com/github/maximeg/email_inquire)\n\nEmailInquire is a library to validate email for format, common typos and one-time email providers.\n\n[Changelog](https://github.com/maximeg/email_inquire/blob/master/CHANGELOG.md)\n\n## Why?\n\nBefore a user is a user, they are a visitor. And they must register to be so. What if they makes a typo while\nentering their email address during the registration ?\nIf they didn't notice, you just lost them. They won't be able to sign in next time.\n\nYour users :\n\n- may not be as tech savvy as you;\n- may not remember exactly their email address;\n- may make a typo while typing their email address (very very common on a mobile keyboard).\n\nWhile we can't do so much for the name part of the email address, for the domain part, we can be smart!\n\nAnd also, we don't want for users to use one-time email addresses (also called burner or disposable\nemail addresses).\n\n## Supported cases\n\nAll supported cases are based on a static validation.\nThe gem does not check (yet) for domain existence (DNS) and prior delivery (MX entries on DNS).\n\n### Email format\n\nThis doesn't strictly follow RFC 5322, it aims at validating email that will be\ndeliverable on Internet. It also takes into account length of email, name part and domain part as\nper SMTP specification.\n\n- `foo@domain..com` =\u003e invalid\n- `foo@my..domain.com` =\u003e invalid\n- `foo@my--domain.com` =\u003e invalid\n- `foo@localhost` =\u003e invalid\n- `foo@123.123.123.123` =\u003e invalid\n- `secrétariat@domain.com` =\u003e invalid\n- `foo+test@domain.com` =\u003e valid\n- ...\n\n### Typos\n\nOne char typo for 43 common email providers (worldwide and from France, United Kingdom and USA):\n\n- `gmil.com` =\u003e hint `gmail.com`\n- `hitmail.com` =\u003e hint `hotmail.com`\n- `outloo.com` =\u003e hint `outlook.com`\n- `virinmedia.com` =\u003e hint `virginmedia.com`\n- ...\n\n### ccTLD typos\n\nccTLD specificity, like United Kingdom `.xx.uk` domains:\n\n- `foo.couk` =\u003e hint `foo.co.uk`\n- `fooco.uk` =\u003e hint `foo.co.uk`\n- `yahoo.uk` =\u003e hint `yahoo.co.uk`\n- `foo.judiciary.uk` =\u003e ok!\n- `foo.uk` =\u003e ok, .uk is open to registration\n- ...\n\n...and same thing with `.co.jp` \u0026 `.com.br` domains.\n\n### Email provider\n\nProviders with an unique domain:\n\n- `gmail.fr` =\u003e hint `gmail.com`\n- `gmail.de` =\u003e hint `gmail.com`\n- `google.com` =\u003e hint `gmail.com`\n- `free.com` =\u003e hint `free.fr`\n- `laposte.com` =\u003e hint `laposte.net`\n- `laposte.fr` =\u003e hint `laposte.net`\n- ...\n\n### Burners\n\n4700 one-time email providers a.k.a. burners, or disposable email\n([source](https://github.com/wesbos/burner-email-providers)):\n\n- `yopmail.com` =\u003e invalid\n- ...\n\n### Known invalid domains\n\n- `example.com` =\u003e invalid\n\n### Custom invalid domains\n\nAdd your own invalid domains:\n\n```ruby\n# in config/initializers/email_inquire.rb\nEmailInquire.custom_invalid_domains \u003c\u003c \"bad-domain.com\"\n```\n\n- `bad-domain.com` =\u003e invalid\n\n### Custom valid domains\n\nTake precedence over all the above rules and make any domain in the list valid, and non hintable.\nAdd your own valid domains:\n\n```ruby\n# in config/initializers/email_inquire.rb\nEmailInquire.custom_valid_domains \u003c\u003c \"good-domain.com\"\n```\n\n- `good-domain.com` =\u003e valid\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'email_inquire'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install email_inquire\n\n## Usage\n\nUse `EmailInquire.validate(email)`, you'll get a `EmailInquire::Response` that represents weither\nor not the email address is valid or may contain a mistake.\n\nMethods of `EmailInquire::Response`:\n\n| Method | Description | Possible values |\n| --- | --- | --- |\n| `#email` | The validated email address | `\"john.doe@gnail.com\"` |\n| `#status` | The status of the validation | `:valid` `:invalid` or `:hint` |\n| `#valid?` | Is the email valid ? | `true` or `false` |\n| `#invalid?` | Is the email invalid ? | `true` or `false` |\n| `#hint?` | Is there a possible mistake and you have to show a hint to the user ? | `true` or `false` |\n| `#replacement` | A proposal replacement email address for when status is `:hint` | `\"john.doe@gmail.com\"` or nil |\n\n### Examples\n\nA valid case:\n\n```ruby\nresponse = EmailInquire.validate(\"john.doe@gmail.com\")\nresponse.status # :valid\nresponse.valid? # true\n```\n\nAn invalid case:\n\n```ruby\nresponse = EmailInquire.validate(\"john.doe@yopmail.com\")\nresponse.status   # :invalid\nresponse.valid?   # false\nresponse.invalid? # true\n```\n\nA hint case:\n\n```ruby\nresponse = EmailInquire.validate(\"john.doe@gmail.co\")\nresponse.status      # :hint\nresponse.valid?      # false\nresponse.hint?       # true\nresponse.replacement # \"john.doe@gmail.com\"\n```\n\nA custom invalid case:\n\n```ruby\n# in config/initializers/email_inquire.rb\nEmailInquire.custom_invalid_domains \u003c\u003c \"bad-domain.com\"\n```\n\nthen:\n```ruby\nresponse = EmailInquire.validate(\"john.doe@bad-domain.com\")\nresponse.status   # :invalid\nresponse.valid?   # false\nresponse.invalid? # true\n```\n\nA custom valid case:\n\n```ruby\n# in config/initializers/email_inquire.rb\nEmailInquire.custom_valid_domains \u003c\u003c \"example.com\" # would be otherwise invalid\nEmailInquire.custom_valid_domains \u003c\u003c \"sfr.com\" # would be otherwise hinted to \"sfr.fr\"\n```\n\nthen:\n```ruby\nresponse = EmailInquire.validate(\"john.doe@example.com\")\nresponse.status   # :valid\nresponse.valid?   # true\nresponse.invalid? # false\n\nresponse = EmailInquire.validate(\"john.doe@sfr.com\")\nresponse.status   # :valid\nresponse.valid?   # true\nresponse.invalid? # false\n```\n\n### Hint\n\nI think it's important to just offer a hint to the user and to not automatically replace the\n**maybe** faulty email address in the form.\n\nA _\"Did you mean xxx@yyy.zzz ?\"_ has the following advantages:\n\n- user remains in charge: we could have hinted against a perfectly valid email;\n- user is educated;\n- mini whaoo effect;\n\nThis _\"Did you mean xxx@yyy.zzz ?\"_ is better being actionable, and appearing to be so: a click or\ntap on it should replace the email by the suggestion.\n\n```\n  +---------------------------------------+  +---------+\n  | john.doe@yaho.com                     |  | Sign Up |\n  +---------------------------------------+  +---------+\n    Did you mean john.doe@yahoo.com ?\n```\n\nNote that you could even have this validation for your Sign In form...\n\n## FAQ\n\n### Why does a perfectly valid corporate domain is hinted ?\n\nThere are a few cases of corporate domains that will be hinted to the related public provider domain:\n\n- `google.com` =\u003e hint `gmail.com`\n- `laposte.fr` =\u003e hint `laposte.net`\n- `sfr.com` =\u003e hint `sfr.fr`\n\nThis is intended. Taking `google.com` (corp) vs. `gmail.com` (public provider):\n\n- there are far more people with a `gmail.com` address rather than people with `google.com` address;\n- employees of Google are well aware of the difference between `google.com` (their employee address)\n  and `gmail.com` (the public email provider offered by their company)\n  and will not be mistaken by a hint;\n- non-tech savvy people are not, and have in mind \"my email address is google\",\n  so not hinting to `gmail.com` would let a lot of actual errors pass.\n\nIf you do not want this, add the affected domains to `EmailInquire.custom_valid_domains`.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n\n### Mutation testing\n\nWe use [mutant](https://github.com/mbj/mutant) to ensure that everything is well\ntested and the code is minimal. Coverage reported should be close to 100%.\n\nRun it with:\n\n```\nbundle exec mutant --include lib --require 'email_inquire.rb' --use rspec -- 'EmailInquire*'\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/maximeg/email_inquire.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximeg%2Femail_inquire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximeg%2Femail_inquire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximeg%2Femail_inquire/lists"}