README

此库将允许您使用现代 PHP7 和 OOP 结构将 ZeroBounce API 集成到您的项目中。

先决条件

您需要 https://zerobounce.net 的一个活动账户来使用此库。从那里，在 API - Keys & Info 下获取您的 API 密钥。

安装

要将此库包含到您的项目中，请使用 Composer 进行安装。

由于我们使用返回类型和类型提示，此库需要 PHP 7.1，并在 PHP 8.1 之前的所有版本上运行。

composer require nickdnk/zerobounce-php

测试

将您的 API 密钥输入到 ZeroBounceTest 文件中，然后运行它。这将使用 ZeroBounce 提供的测试电子邮件，不会消耗您的信用。

如何使用

use nickdnk\ZeroBounce\Email;
use nickdnk\ZeroBounce\Result;
use nickdnk\ZeroBounce\ZeroBounce;

// You can modify the timeout using the second parameter. Default is 15.
// You an also pass proxy options to Guzzle using the third parameter.
// See https://docs.guzzlephp.org/en/stable/request-options.html#proxy for details.
$handler = new ZeroBounce('my_api_key', 30, ['https' => 'https://my-proxy-server']);

$email = new Email(
    
    // The email address you want to check
    'some-email@domain.com',
    
    // and if you have it, the IP address - otherwise null or omitted
    '123.123.123.123'

);

try {

    // Validate the email
    $result = $handler->validateEmail($email);
    
    if ($result->getStatus() === Result::STATUS_VALID) {
        
        // All good
        
        if ($result->isFreeEmail()) {
            
            // Email address is free, such as @gmail.com, @hotmail.com.
            
        }
        
        /**
        * The user object contains metadata about the email address
        * supplied by ZeroBounce. All of these may be null or empty
        * strings, so remember to check for that. 
        */
        $user = $result->getUser();
        
        $user->getCountry();
        $user->getRegion();
        $user->getZipCode();
        $user->getCity();
        $user->getGender();
        $user->getFirstName();
        $user->getLastName();
        
    } else if ($result->getStatus() === Result::STATUS_DO_NOT_MAIL) {
        
        // The substatus code will help you determine the exact issue:
        
        switch ($result->getSubStatus()) {
            
            case Result::SUBSTATUS_DISPOSABLE:
            case Result::SUBSTATUS_TOXIC:
                // Toxic or disposable.
                break;
                
                
            case Result::SUBSTATUS_ROLE_BASED:
                // admin@, helpdesk@, info@ etc; not a personal email
                break;
            
            // ... and so on.
                
        }
        
    } else if ($result->getStatus() === Result::STATUS_INVALID) {
        
        // Invalid email.
        
    } else if ($result->getStatus() === Result::STATUS_SPAMTRAP) {
        
        // Spam-trap.
        
    } else if ($result->getStatus() === Result::STATUS_ABUSE) {
        
        // Abuse.
        
    } else if ($result->getStatus() === Result::STATUS_CATCH_ALL) {
        
        // Address is catch-all; not necessarily a private email.
        
    } else if ($result->getStatus() === Result::STATUS_UNKNOWN) {
        
        // Unknown email status.
       
    }
    
    /*
     * To find out how to use and react to different status and
     * substatus codes, see the ZeroBounce documentation at:
     * https://www.zerobounce.net/docs/?swift#version-2-v2
     */

} catch (\nickdnk\ZeroBounce\HttpException $exception) {

   // ZeroBounce returned an error of some kind. Message is best-effort parsing.
   $exception->getMessage();
   // The response is available here also.
   // The HTTP code is 200 for 400-range problems, such as invalid credentials,
   // so don't rely too much on that. It is included mostly for debugging purposes.
   $exception->getResponse(); 

} catch (\nickdnk\ZeroBounce\ConnectionException $exception) {

   // There was a problem connecting to ZeroBounce or the connection timed out waiting for a reply.
   $exception->getMessage(); // will always return generic "request timed out or failed" message

} catch (\nickdnk\ZeroBounce\APIError $exception) {

   // Base exception. Both HttpException and ConnectionException extend from this, so you can
   // catch this to handle both errors. The somewhat odd naming for this was to avoid
   // introducing breaking changes when HttpException and ConnectionException was added.
   $exception->getMessage();

}