PHPackages oxemis/oxibounce - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. oxemis/oxibounce ActiveLibrary[API Development](/categories/api) oxemis/oxibounce ================ PHP wrapper for the OxiBounce API v2.0.0(1y ago)413MITPHP Since Apr 17Pushed 1y ago2 watchersCompare [ Source](https://github.com/oxemis/oxibounce-php)[ Packagist](https://packagist.org/packages/oxemis/oxibounce)[ RSS](/packages/oxemis-oxibounce/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (2)Dependencies (1)Versions (3)Used By (0) Official OxiBounce PHP Wrapper ============================== [](#official-oxibounce-php-wrapper) [![MIT License](https://camo.githubusercontent.com/48593de0035d3aebc555d81be22bb1136d0741866cc69614fd437cacc7553cf7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d3030374543372e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/48593de0035d3aebc555d81be22bb1136d0741866cc69614fd437cacc7553cf7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d3030374543372e7376673f7374796c653d666c61742d737175617265)[![Current Version](https://camo.githubusercontent.com/97f85f046265623c4b26076add9bcc55f9608152c20e78f07076369977c77d05/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d677265656e2e737667)](https://camo.githubusercontent.com/97f85f046265623c4b26076add9bcc55f9608152c20e78f07076369977c77d05/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d677265656e2e737667) Overview -------- [](#overview) This repository contains the official PHP wrapper for the OxiBounce API. To get started, create an account and request your free credits on [this page](https://account.oxemis.com/) This library is a wrapper for the [OxiBounce API](https://api.oxibounce.com) but you don't have to know how to use the API to get started with this library. What is OxiBounce ? ------------------- [](#what-is-oxibounce-) OxiBounce is an online service dedicated to the verification of emails addresses. It will not only validate that the address is valid but it will also check the **existence of the email**. Table of contents ----------------- [](#table-of-contents) - [Compatibility](#compatibility) - [Installation](#installation) - [Authentication](#authentication) - [Getting information about your account](#getting-information-about-your-account) - [Checking an email the best way](#checking-an-email-the-best-way) - [Asynchronous check](#asynchronous-check) - [Synchronous check](#synchronous-check) - [What are the meaning of the EmailCheckResult properties ?](#what-are-the-meaning-of-the-emailcheckresult-properties-) - [Contribute / Need help ?](#contribute--need-help-) Compatibility ------------- [](#compatibility) This library requires **PHP v7.4** or higher. Installation ------------ [](#installation) Use the below code to install the wrapper: `composer require oxemis/oxibounce` Authentication -------------- [](#authentication) This library is a wrapper to the [OxiBounce API](https://api.oxibounce.com). You can request an API KEY in your [OxiBounce Account](https://account.oxemis.com). Free credits are offered. You should export your API\_LOGIN and API\_PASSWORD in order to use them in this library : ``` export OXIBOUNCE_API_LOGIN='your API login' export OXIBOUNCE_API_PWD='your API password' ``` Initialize your **OxiBounce** Client: ``` require_once 'vendor/autoload.php'; use \Oxemis\OxiBounce\OxiBounceClient; // getenv will allow us to get the OXIBOUNCE_API_LOGIN/OXIBOUNCE_API_PWD variables we created before: $apilogin = getenv('OXIBOUNCE_API_LOGIN'); $apipwd = getenv('OXIBOUNCE_API_PWD'); $oxibounce = new OxiBounceClient($apilogin, $apipwd); // or, without using environment variables: $apilogin = 'your API login'; $apipwd = 'your API password'; $oxibounce = new OxiBounceClient($apilogin, $apipwd); ``` Getting information about your account -------------------------------------- [](#getting-information-about-your-account) You will find all the information about your OxiBounce account with the "**UserAPI**" object. Informations returned are documented in the class. ``` require_once "vendor/autoload.php"; use \Oxemis\OxiBounce\OxiBounceClient; $client = new OxiBounceClient(API_LOGIN,API_PWD); $user = $client->userAPI->getUser(); echo "Account :" . $user->getEmail() . "\n" . "Remaining credits : " . $user->getCredits() . "\n"; ``` Checking an email the best way ------------------------------ [](#checking-an-email-the-best-way) OxiBounce allows you to check an email address with two methods : - **Asynchronously** : this is the best method to get better results but it can take time to validate completly an address. Use this method for a background worker for instance. - **Synchronously** : this is the method you should prefer if you want to validate emails on a form (for example). You will be able to specify a "timeout" after which the verification method will stop in order to not block users. The more time you let, the better the results will be. > **The complete validation of an email address can take time !** > > More than **20 different tests** are carried out, some of which depend on the performance of the mail servers of the addresses tested. > > We always do our best to return the result as quickly as possible (within seconds), but sometimes the whole test can take several minutes! > > **If you are limited by time, use the "Synchronous" method with an appropriate timeout**. Asynchronous check ------------------ [](#asynchronous-check) The async method will require you to : - Start a test that will return you an ID - Periodically, check this ID to check if the test is "PENDING" or "DONE" **Step 1 : run the test** ``` require_once 'vendor/autoload.php'; use Oxemis\OxiBounce\OxiBounceClient; use Oxemis\OxiBounce\Objects\EmailCheck; use Oxemis\OxiBounce\Objects\EmailCheckResult; // Create the Client $apilogin = 'your API login'; $apipwd = 'your API password'; $client = new OxiBounceClient($apilogin, $apipwd); // Run the check // You can specify multiple addresses separated with a ";" (up to 50) // You will have to keep the returned array (one element by email tested) to get results. $tests = $client->checkAPI->runCheckAsync("email1@example.com"); ``` **Step 2 : get the status and results** ``` // We'll have to check that all tests are carried out. // Remember that tests can take minutes ! // Other option is to use the synchronous method (which handle a timeout), see next chapter ! $pending = true; while ($pending) { // $tests is the array returned by runCheckAsync() $results = $client->checkAPI->getCheckResultAsync($tests); // Will be set to true below if some tests are still "PENDING" $pending = false; // Wait for results foreach ($results as $result) { if ($result->getStatus() == EmailCheck::STATUS_PENDING) // Some tests are still pending $pending = true; // Waiting for 1 second sleep(1); } } } // Use the results foreach ($results as $result) { switch ($result->getResult()) { case EmailCheckResult::RESULT_OK: // The address is valid. echo $result->getEmail() . " is valid !"; break; case EmailCheckResult::RESULT_KO: // The address is invalid. echo $result->getEmail() . " is invalid !"; break; case EmailCheckResult::RESULT_NOTSURE: // The tests did not reveal whether the address is valid or not. // Other properties ($result->isRisky() for example) can give you more // information to let you decide whether or not to authorize the address. echo $result->getEmail() . " is not sure !"; break; } } ``` Synchronous check ----------------- [](#synchronous-check) The synchronous method manage a limit of time for the checks. Here is a simple sample : ``` require_once 'vendor/autoload.php'; use Oxemis\OxiBounce\OxiBounceClient; use Oxemis\OxiBounce\Objects\EmailCheck; use Oxemis\OxiBounce\Objects\EmailCheckResult; // Create the Client $apilogin = 'your API login'; $apipwd = 'your API password'; $client = new OxiBounceClient($apilogin, $apipwd); // Run the check // You can specify multiple addresses separated with a ";" (up to 50) // The second parameter is the time out (in seconds). $results = $client->checkAPI->checkEmails("email1@example.com", 10); // Use the results foreach ($results as $result) { if ($result->getStatus() == EmailCheckResult::STATUS_DONE) { // The test is done, use object properties switch ($result->getResult()) { case EmailCheckResult::RESULT_OK: // The address is valid. echo $result->getEmail() . " is valid !"; break; case EmailCheckResult::RESULT_KO: // The address is invalid. echo $result->getEmail() . " is invalid !"; break; case EmailCheckResult::RESULT_NOTSURE: // The tests did not reveal whether the address is valid or not. // Other properties ($result->isRisky() for example) can give you more // information to let you decide whether or not to authorize the address. echo $result->getEmail() . " is not sure !"; break; } } else { // This test is not finished (but timeout is reached) echo $result->getEmail() . " the test is still 'PENDING'."; } } ``` > **What to do with "PENDING" checks (timeout reached) ?** > > Short answer : consider them as "NOT\_SURE". > > You can also store there "ID" (`$result->getId()`) in order to get the results later with the `$client->checkAPI->getCheckResultAsyncFromId()` method. What are the meaning of the `EmailCheckResult` properties ? ----------------------------------------------------------- [](#what-are-the-meaning-of-the-emailcheckresult-properties-) The `EmailCheckResult` structure contains a lot of informations about the test results. Each one is documented as PHPDoc if you need to get a description in your IDE. PropertyMeaning**Result**The result of the test. Can be RESULT\_OK, RESULT\_KO or RESULT\_NOTSURE. For more details, see “Reason”.**Reason**The detailled reason of the result (many codes are availables, see [page 2 of this document](https://www.oxemis.com/docs/oxibounce_status_desc.pdf)).**Domain**The domain of the email.**IsFormatValid**True if the email address has a valid format.**IsDisposable**Indicates that the address is a disposable address. Disposable addresses can be dangerous because they are not necessarily associated with a single recipient (it is sometimes enough to know the address to consult its contents). **Never send messages containing confidential information to such addresses**.**IsFreeMail**Indicates that the address is a “free” address, therefore not associated with a particular company.**IsRisky**Indicates that the address or its domain is identified as potentially dangerous. **It is strongly recommended not to send to these addresses to preserve your reputation.****IsRobot**Indicates that the e-mail address appears to be associated with a robot and not with a real person or a department of a company. **Behind some of these addresses are hidden spamtraps**. So be very careful.**IsRole**Indicates that the address is that of a department of a company or that it is a generic address (contact@…).**MailSystem**Contains, if identified, the email system used by the owner of the email address.**Suggestion**In case of an invalid address, OxiBounce will be able to suggest a correction (gmial.com at the link of gmail.com for example). **To be used with caution and manual validation of course**.Managing lists -------------- [](#managing-lists) In addition to the simple checks, you also have the ability to add a list of emails, start / stop the analysis of this list, get the results for the whole list and delete the list. Here's a simple sample to upload a JSON list to OxiBounce : ``` require_once 'vendor/autoload.php'; use Oxemis\OxiBounce\OxiBounceClient; use Oxemis\OxiBounce\Objects\EmailList; // Create the Client $apilogin = 'your API login'; $apipwd = 'your API password'; $client = new OxiBounceClient($apilogin, $apipwd); // Upload a JSON file as a list $list = $client->listAPI->addList("./test.json"); // Store the list ID to interact with echo 'List uploaded as #' . $list->getId(); ``` Once uploaded, you'll get an EmailList Object with and `Id` that you can use to start (or stop with stopList) the list : ``` // Start the list analysis $client->listAPI->startList($list->getId()); ``` You can follow the processing of the list by refreshing the list object : ``` // Get refreshed information about the list $list = $client->listAPI->getList($list->getId()); echo "List is : " . $list->getStatus(); // PENDING, DONE, CANCELED ``` And then get the results (when DONE or CANCELED) : ``` // Get results for list $result = $client->listAPI->getListResults($list->getId()); foreach ($result as $emailCheckResult) { echo $emailCheckResult->getEmail() . " : " . $emailCheckResult->getResult() . "\n"; } ``` You also have the ability to completly remove a list from our servers : ``` // Delete the list $client->listAPI->deleteList($list->getId()); ``` Contribute / Need help ? ------------------------ [](#contribute--need-help-) Feel free to ask anything, and contribute to this project. Need help ? 👉 ### Health Score 26 — LowBetter than 43% of packages Maintenance37 Infrequent updates — may be unmaintained Popularity9 Limited adoption so far Community8 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~187 days Total 2 Last Release 566d ago Major Versions v1.0.0 → v2.0.02024-10-21 ### Community Maintainers ![](https://www.gravatar.com/avatar/ddb5ecce29e61a4d9664d7d2f27caebc2c504560a6a8d2007299001cd8d5a3d5?d=identicon)[oxemis](/maintainers/oxemis) --- Top Contributors [![laudep59](https://avatars.githubusercontent.com/u/98906510?v=4)](https://github.com/laudep59 "laudep59 (8 commits)") ### Embed Badge ![Health badge](/badges/oxemis-oxibounce/health.svg) ``` [![Health](https://phpackages.com/badges/oxemis-oxibounce/health.svg)](https://phpackages.com/packages/oxemis-oxibounce) ``` ### Alternatives [tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[convertkit/convertkitapi Kit PHP SDK for the Kit API 2167.1k1](/packages/convertkit-convertkitapi)[mapado/rest-client-sdk Rest Client SDK for hydra API 1125.9k2](/packages/mapado-rest-client-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)