README

Verifalia API - PHP SDK和辅助库

此SDK库与Verifalia集成，允许在PHP v7.0及以上版本中验证电子邮件地址。

Verifalia是一个在线服务，提供电子邮件验证和邮件列表清理；它帮助企业降低退信率，保护发件人声誉，并确保其电子邮件活动送达目标收件人。Verifalia可以实时和批量验证电子邮件地址，使用其API或客户端区域；它还提供各种功能和设置，以根据用户需求自定义验证过程。

Verifalia的电子邮件验证过程包括几个步骤，每个步骤只需几分之一秒：它检查每个电子邮件地址的格式和语法（RFC 1123、RFC 2821、RFC 2822、RFC 3490、RFC 3696、RFC 4291、RFC 5321、RFC 5322和RFC 5336）、域名和DNS记录、邮件交换器和邮箱存在，支持国际化域名和邮箱。它还检测危险电子邮件类型，如捕获所有、一次性或垃圾陷阱 / 蜜罐。

Verifalia为每次电子邮件验证提供详细且准确的报告：将每个电子邮件地址分类为可投递、不可投递、危险或未知，并分配其独家超过40个的状态码之一。它还解释了不可投递的原因，并提供了全面验证细节。该服务允许用户为每次验证选择所需的品质级别、等待超时、去重偏好、数据保留设置和回调偏好。

当然，Verifalia永远不会向联系人发送电子邮件或与任何人共享用户数据。

有关Verifalia的更多信息，请参阅https://verifalia.com

入门

将Verifalia邮箱验证库添加到您的PHP项目的最有效方法是使用Composer，它将自动下载和安装所需文件来自Packagist。安装Composer后，从项目的根目录运行以下命令

php composer.phar require verifalia/sdk

对于Windows用户，可以运行的替代命令是

composer require verifalia/sdk

命名约定

此包遵循PSR-4命名约定为其类命名，这意味着您甚至可以使用自己的自动加载器轻松加载它们。

身份验证

首先：Verifalia API的认证是通过您的根Verifalia账户的凭据或您的用户（以前称为子账户）的凭据来执行的：如果您没有Verifalia账户，只需注册一个免费账户。出于安全考虑，始终建议创建并使用一个专门的用户来访问API，这样就可以只为它分配所需的特定权限。

有关Verifalia API认证的更多信息，请访问https://verifalia.com/developers#authentication

通过基本身份验证进行身份验证

认证Verifalia API的最直接方法涉及使用用户名和密码对。这些凭据可以在创建VerifaliaRestClient类的新实例时应用，作为与Verifalia API交互的初始步骤：提供的用户名和密码将自动通过HTTP基本认证方法发送到API。

use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;

$verifalia = new VerifaliaRestClient([
    VerifaliaRestClientOptions::USERNAME => 'your-username-here',
    VerifaliaRestClientOptions::PASSWORD => 'your-password-here'
]);

通过承载令牌进行身份验证

与HTTP基本认证相比，Bearer认证提供了更高的安全性，因为后者需要在每次API调用时发送实际的凭据，而前者仅在第一次专门的认证请求时需要。另一方面，Bearer认证所需的第一次认证请求需要相当长的时间。

⚠️如果您只需要执行单个请求，使用HTTP基本认证（如上所述）提供相同的安全级别，且速度更快。

use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;
use Verifalia\Security\BearerAuthenticationProvider;

$verifalia = new VerifaliaRestClient([
    VerifaliaRestClientOptions::AUTHENTICATION_PROVIDER => 
        new BearerAuthenticationProvider('your-username-here', 'your-password-here')
]);

通过X.509客户端证书（TLS双向身份验证）进行身份验证

除了上述认证方法之外，此SDK还支持通过TLS协议使用加密的X.509客户端证书来通过TLS协议对Verifalia API进行认证，这称为双向TLS认证（mTLS）或双向认证。这种方法提供最高程度的安全性，因为每次请求都只发送通过加密派生的密钥（而不是实际的凭据）。什么是X.509 TLS客户端证书认证？

use Verifalia\VerifaliaRestClient;
use Verifalia\VerifaliaRestClientOptions;

$verifalia = new VerifaliaRestClient([
    VerifaliaRestClientOptions::CERTIFICATE => '/home/gfring/Documents/pollos.pem'
]);

验证电子邮件地址

与验证/验证电子邮件地址相关的每个操作都是通过您上面创建的VerifaliaRestClient实例公开的emailValidations字段执行的。该属性公开了一些有用的函数：在接下来的几段中，我们将查看最常用的函数，因此强烈建议您探索库并查看内置的帮助以了解其他机会。

库自动等待电子邮件验证作业的完成：如果需要，您可以调整等待选项并更全面地控制整个底层轮询过程。请参阅下面的等待选项部分以获取更多详细信息。

如何验证/验证电子邮件地址

要从PHP应用程序验证电子邮件地址，您可以调用submit()方法：它接受一个或多个电子邮件地址以及您希望传递给Verifalia的任何验证选项，包括预期的结果质量、去重偏好、处理优先级。

注意：如果您需要验证一串电子邮件地址列表，建议一次性通过submit()方法提交（请参阅下一节），而不是迭代源集并逐个提交地址。一次性提交不仅更快，还可以检测并标记重复项——这是一个在逐个验证电子邮件地址时不可用的功能。

以下示例展示了如何使用默认选项使用此库验证电子邮件地址

use Verifalia\VerifaliaRestClient;

$verifalia = new VerifaliaRestClient(...); // See above

// Verifies an email address

$job = $verifalia->emailValidations->submit('batman@gmail.com');

// Print some results

$entry = $job->entries[0];

echo 'Classification: ' . $entry->classification;
echo 'Status: ' . $entry->status;

// Output:
// Classification: Deliverable
// Status: Success

一旦submit()成功完成，生成的验证作业将保证完成，其结果数据（例如，其entries字段）将可用于使用。

正如您可能预料的，每个条目都可能包含有关验证的电子邮件地址的许多额外详细信息

以下是另一个示例，展示了Verifalia提供的一些额外结果细节

use Verifalia\VerifaliaRestClient;

$verifalia = new VerifaliaRestClient(...); // See above

// Verifies an email address

$job = $verifalia->emailValidations->submit('bat[man@gmal.com');

// Print some results

$entry = $job->entries[0];

echo 'Classification: ' . $entry->classification . "\n";
echo 'Status: ' . $entry->status . "\n";
echo 'Syntax failure index: ' . $entry->syntaxFailureIndex . "\n";

if (!empty(entry->suggestions)) {
    echo "Suggestions\n";
    
    foreach ($entry->suggestions as $suggestion) {
        echo '- ' . $suggestion . "\n";
    }
}

// Output:
// Classification: Undeliverable
// Status: InvalidCharacterInSequence
// Syntax failure index: 3
// Suggestions:
// - batman@gmail.com

如何验证/验证电子邮件地址列表

要验证一串电子邮件地址，您仍然可以调用submit()函数，该函数也接受一个包含要验证的电子邮件地址的字符串数组

use Verifalia\VerifaliaRestClient;

$verifalia = new VerifaliaRestClient(...); // See above

// Verifies the list of email addresses

$job = $verifalia->emailValidations->submit([
    'batman@gmail.com',
    'steve.vai@best.music',
    'samantha42@yahoo.de',
]);

// Print some results

foreach ($job->entries as $entry) {
    echo $entry->emailAddress . ' => ' . $entry->classification;
}

// Output:
// batman@gmail.com => Deliverable
// steve.vai@best.music => Undeliverable
// samantha42@yahoo.de => Deliverable

处理选项

在提交一个或多个电子邮件地址以进行验证时，您可以指定多个选项，这些选项会影响Verifalia处理引擎的行为以及API消费者的验证流程。

品质级别

Verifalia提供三个不同的质量级别——即标准、高和极端——这决定了电子邮件验证引擎应如何处理临时不可投递问题、较慢的邮件交换器和其他可能影响验证结果质量的可变问题。ValidationRequest类接受一个quality字段，允许指定所需的质最级别；以下是一个示例，展示如何使用高质量级别验证电子邮件地址

$request = new ValidationRequest('batman@gmail.com');
$request->quality = QualityLevelName::HIGH;

$job = $verifalia->emailValidations->submit($request);

去重模式

submit()方法还可以批量接受和验证多个电子邮件地址，并允许指定如何处理属于同一输入集的重复条目；Verifalia支持一个安全去重模式，该模式严格遵循旧的IETF标准，以及一个宽松模式，该模式更符合当今大多数邮件交换器配置中的设置。

在下一个示例中，我们展示了如何使用宽松去重模式导入和验证电子邮件地址列表，并标记重复条目

$request = new ValidationRequest([
    'batman@gmail.com',
    'steve.vai@best.music',
    'samantha42@yahoo.de',
]);
$request->deduplication = DeduplicationMode::RELAXED;

$job = $verifalia->emailValidations->submit($request);

数据保留

Verifalia会根据在账户级别定义的数据保留策略自动删除完成的电子邮件验证作业，该策略最终可以在用户级别进行覆盖：您可以使用Verifalia客户区来配置这些设置。

您还可以指定每个作业的数据保留策略，该策略控制提交的电子邮件验证作业的存活时间；为此，相应地设置ValidationRequest实例的retention字段。

例如，以下是如何在验证电子邮件地址时设置10分钟的数据保留策略

$request = new ValidationRequest('batman@gmail.com');
$request->retention = DateInterval::createFromDateString('10 minutes');

$job = $verifalia->emailValidations->submit($request);

等待选项

默认情况下，submit()方法将电子邮件验证作业提交给Verifalia并等待其完成；整个过程可能需要一些时间才能完成，具体取决于Verifalia账户的计划、提交中包含的电子邮件地址数量、指定的质量级别和其他网络因素，包括测试邮件交换器的延迟。

在等待特定电子邮件验证作业完成时，库会自动轮询底层的Verifalia API，直到结果准备就绪；默认情况下，它会尝试利用Verifalia API v2.4引入的长轮询模式，这有助于最小化请求数量并更快地获取验证结果。

避免等待

在某些情况下（例如在微服务架构中），为了避免等待任务完成，并直接向Verifalia API排队，可能更可取：在这种情况下，库将仅返回作业概述（而不是其验证结果），并且需要使用get()方法检索验证结果。

为此，可以将WaitOptions::$noWait指定为submit()方法的waitOptions参数的值，如下一个示例所示

$verifalia = new VerifaliaRestClient(...); // See above
$request = new ValidationRequest(...) // See above;

$job = $verifalia->emailValidations->submit($request, WaitOptions::$noWait);

echo 'Status: ' . $job->overview->status;

// Status: InProgress

进度跟踪

对于包含大量电子邮件地址的作业，在Verifalia电子邮件验证引擎处理它们时跟踪进度可能很有用；为此，可以创建一个WaitOptions类的实例，并提供一个可调用对象，该对象最终将通过progress字段接收进度通知。

以下是定义进度通知处理程序的方法，该处理程序将提交作业的进度百分比显示在控制台窗口中

use Verifalia\EmailValidations\ValidationOverview;
use Verifalia\EmailValidations\WaitOptions;

$verifalia = new VerifaliaRestClient(...); // See above
$request = new ValidationRequest(...) // See above;

$waitOptions = new WaitOptions(function (ValidationOverview $overview) {
    echo 'Job status: ' . $overview->status;
    
    if ($overview->progress !== null) {
        echo 'Progress: ' . $overview->progress->percentage . '%';
    }
});

$job = $verifalia->emailValidations->submit($request, $waitOptions);

完成回调

除了每个电子邮件验证作业外，还可以指定Verifalia在作业完成后调用的URL（POST）：该URL必须使用HTTPS或HTTP方案，并且可以在互联网上公开访问。有关完成回调的更多信息，请参阅https://verifalia.com/developers#email-validations-completion-callback

要指定完成回调URL，请将ValidationRequest实例传递给submit()方法，并相应地设置其completionCallback字段，如下面的示例所示

$verifalia = new VerifaliaRestClient(...); // See above
$request = new ValidationRequest(...) // See above;

$request->completionCallback = new CompletionCallback('https://your-website-here/foo/bar');

$job = $verifalia->emailValidations->submit($request, $waitOptions);

请注意，完成回调是异步调用的，并且您的回调URL可能需要几秒钟才能被调用。

检索作业

可以通过get()方法检索作业，该方法返回所需电子邮件验证作业的Validation实例。在执行此操作时，库会自动等待作业完成，可以通过传递一个waitOptions参数到上述方法来调整此行为，其方式与submit()方法中描述的完全相同；请参阅等待选项部分以获取更多详细信息。

以下是一个示例，说明如何根据其标识符检索作业

$job = $verifalia->emailValidations->get('ec415ecd-0d0b-49c4-a5f0-f35c182e40ea');

完成后不要忘记清理

Verifalia将自动删除完成后作业，删除策略是可配置的（请参阅相关部分），但强烈建议您尽快删除已完成的作业，以保护隐私和安全。为此，您可以通过调用delete()方法并传递您希望删除的作业ID来完成此操作

$verifalia->emailValidations->delete('ec415ecd-0d0b-49c4-a5f0-f35c182e40ea');

一旦删除，作业就会消失，并且无法检索其电子邮件验证结果。

管理信用额度

要管理您的Verifalia账户的积分，可以使用上面创建的VerifaliaRestClient实例公开的credits属性。

获取信用额度余额

您可能需要在您的账户上执行的最常见任务之一是检索免费每日积分和积分包的数量。为此，您可以使用返回Balance对象的getBalance()方法，如下面的示例所示

$balance = $verifalia
    ->credits
    ->getBalance();

echo 'Credit packs: ' . $balance->creditPacks . "\n";
echo 'Free daily credits: ' . $balance->freeCredits . "\n";
echo 'Free daily credits will reset in ' . $balance->freeCreditsResetIn . "\n";

// Prints out something like:
// Credit packs: 956.332
// Free daily credits: 128.66
// Free daily credits will reset in 09:08:23

要为您的Verifalia账户添加积分包，请访问https://verifalia.com/client-area#/credits/add。

变更日志/新功能

本节列出了当前主版本的库的更改日志：对于旧版本，请参阅项目发布。

v3.0

发布于2024年2月1日

添加了对Verifalia API v2.5的支持
添加了对分类覆盖规则的支持
添加了对AI驱动的建议的支持
添加了对客户端证书身份验证的支持
添加了对载体身份验证的支持
添加了对完成回调的支持
添加了对提交和轮询等待时间的支持
添加了PHPDoc注释
优化等待作业完成时的睡眠时间强制执行
重大变更：最低PHP版本要求提升至 PHP 7.0
重大变更：现在默认情况下，submit() 方法将等待电子邮件验证作业完成
重大变更：将 IAuthenticator 接口重命名为 AuthenticationProvider

verifalia / sdk

维护者

详细信息