=== BounceBell Email Verification ===
Contributors: sanilts
Tags: email verification, email validation, disposable email, fake registrations, woocommerce
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Stops fake, mistyped and throwaway email addresses in your forms before they are saved. Powered by the BounceBell email verification API.

== Description ==

BounceBell Email Verification checks each email address typed into your forms while the form is being sent. Addresses that do not exist, or that are throwaway, are refused with a clear message, so the visitor can fix a typo straight away.

This is the official WordPress plugin of [BounceBell](https://bouncebell.com/integrations/wordpress), built and maintained by Astrizon Technology Solutions Pvt Ltd, the company that owns and runs the BounceBell service.

= What it refuses =

* Invalid addresses: the mailbox does not exist. On by default.
* Disposable addresses: temporary inboxes that stop working after a while. On by default.
* Shared role addresses, like info@ or sales@. Off by default.
* Free mailboxes, like Gmail or Outlook.com, for business sign-ups. Off by default.

Catch-all and unknown addresses are always allowed. When BounceBell spots a likely typo, the message adds a suggestion such as "Did you mean name@gmail.com?".

You can write your own message for each case.

= Where it checks =

* WordPress registration (wp-login.php, and wp-signup.php on multisite)
* Comments from visitors who are not signed in
* WooCommerce checkout, classic and block
* WooCommerce My Account registration
* Contact Form 7
* WPForms
* Gravity Forms
* Elementor Pro Forms
* Ninja Forms
* Formidable Forms
* Fluent Forms
* Forminator
* Jetpack Forms

Each place has its own switch. Form plugins only appear in the settings when they are active. All checks run on your server, inside each plugin's own validation step, so they cannot be skipped by turning off JavaScript.

Jetpack Forms has no field validation hook. The plugin uses Jetpack's submission filter instead, which stops the submission and shows the message. Only the first email field of a Jetpack form is checked.

= Never blocks by mistake =

If no API key is saved, the key is wrong, your credits run out, BounceBell cannot be reached in time or the answer is unknown, the form is let through. The reason is shown to administrators as "Last problem" on the settings screen, never to visitors. After such a problem, checks pause for a few minutes, so a broken connection does not slow your forms down.

= Saves credits =

Each answer is kept on your site for 30 days, so an address that is sent again in that time costs no credit. Unknown answers are not kept.

= Check existing users =

The Check existing users tool sends the addresses of your current users to BounceBell in batches, then shows how many are valid, invalid or risky, with a CSV download. Nothing is changed or deleted. The Users screen also gets an Email check column with each stored result.

= Requirements =

The plugin needs a BounceBell account and a secret API key. Every new account gets free credits to start. Prices are listed at https://bouncebell.com/pricing.

== External services ==

This plugin connects to the BounceBell API at https://bouncebell.com/api/v1, provided by Astrizon Technology Solutions Pvt Ltd, to check whether an email address exists and can receive mail.

* What is sent: the email address being checked, and your BounceBell API key to identify your account. No other personal data is sent, and no data about the visitor's browser or IP address.
* When it is sent: only after you save an API key, and only when someone sends a form that you have switched on (for example registration, a comment, checkout or a contact form) with an address that has no stored answer from the last 30 days.
* Test connection: sends only your API key, to read your account name and credit balance.
* Check existing users: only when an administrator starts it, the email addresses of the site's users are sent in batches.
* Caching: answers are stored on your site for 30 days, keyed by a one-way hash of the address, so the same address is not sent again in that time.

BounceBell terms of service: https://bouncebell.com/legal/terms
BounceBell privacy policy: https://bouncebell.com/legal/privacy

== Installation ==

1. Install and activate the plugin from the Plugins screen, or upload the bouncebell-email-verification folder to /wp-content/plugins/.
2. Create a BounceBell account at https://app.bouncebell.com/signup and copy a secret key from the API page of your dashboard.
3. Go to Settings > BounceBell, paste the key and click Test connection.
4. Choose what to refuse and where to check, then save.

== Frequently Asked Questions ==

= Do I need an API key? =

Yes. Nothing is checked until a key is saved.

= Can a visitor get stuck if BounceBell is down? =

No. If BounceBell cannot answer within a few seconds, the form is let through and the problem is shown to administrators on the settings screen.

= How many credits will my site use? =

One per new address that is sent through a form you switched on. Answers are kept for 30 days, so repeat submissions of the same address are free. Unknown answers do not use a credit.

= Are users I add in wp-admin checked? =

No. Only forms that visitors fill in are checked. Use the Check existing users tool to review addresses already on the site.

= Can I skip the check for some addresses? =

Yes, with the bouncebell_skip_check filter. For example, to skip every address at your own domain:

`add_filter( 'bouncebell_skip_check', function ( $skip, $email ) { return $skip || '@example.com' === substr( strtolower( $email ), -12 ); }, 10, 2 );`

= Which filters are available? =

* bouncebell_skip_check: skip the check for an address.
* bouncebell_refuse_reason: change the decision for an address.
* bouncebell_refuse_message: change the message shown.
* bouncebell_verify_timeout: seconds BounceBell may spend on one address (default 6).
* bouncebell_cache_days: days an answer is kept (default 30).

== Screenshots ==

1. Settings: connection, what to refuse, messages and where to check.
2. A registration refused for an address that does not exist, with a typo suggestion.
3. Check existing users with counts and the CSV download.
4. The Email check column on the Users screen.

== Changelog ==

= 1.0.0 =
* First release: checks for WordPress registration, comments, WooCommerce, Contact Form 7, WPForms, Gravity Forms, Elementor Pro Forms, Ninja Forms, Formidable Forms, Fluent Forms, Forminator and Jetpack Forms, with a 30 day cache, the Check existing users tool and the Email check column.
