pyzit / tempmail
Official PHP SDK for the Pyzit disposable email detector API
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
Requires (Dev)
- php-mock/php-mock-phpunit: ^2.9
- phpunit/phpunit: ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-07 18:45:25 UTC
README
██████╗ ██╗ ██╗███████╗██╗████████╗
██╔══██╗╚██╗ ██╔╝╚══███╔╝██║╚══██╔══╝
██████╔╝ ╚████╔╝ ███╔╝ ██║ ██║
██╔═══╝ ╚██╔╝ ███╔╝ ██║ ██║
██║ ██║ ███████╗██║ ██║
╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝
████████╗███████╗███╗ ███╗██████╗ ███╗ ███╗ █████╗ ██╗██╗
╚══██╔══╝██╔════╝████╗ ████║██╔══██╗████╗ ████║██╔══██╗██║██║
██║ █████╗ ██╔████╔██║██████╔╝██╔████╔██║███████║██║██║
██║ ██╔══╝ ██║╚██╔╝██║██╔═══╝ ██║╚██╔╝██║██╔══██║██║██║
██║ ███████╗██║ ╚═╝ ██║██║ ██║ ╚═╝ ██║██║ ██║██║███████╗
╚═╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚══════╝
The official PHP SDK for the Pyzit Disposable Email Detector API
Stop fake signups. Block throwaway addresses. Protect your platform.
◈ What is this?
pyzit/tempmail is the official PHP client for the Pyzit Disposable Email API — a service that detects throwaway, temporary, and fake email addresses in real time.
User submits email SDK validates it Your app decides
───────────────── ───────────────── ───────────────
user@mailnator.com ──────► is_disposable: True ──────► ✗ Reject signup
hi@yourcompany.com ──────► is_disposable: False ──────► ✓ Allow signup
Works with Laravel, Symfony, WordPress, plain PHP scripts — simple Composer integration.
◈ Table of contents
- Installation
- Quick start
- API tiers
- All methods
- Response models
- Error handling
- Framework integrations
- Configuration
- Development
◈ Installation
composer require pyzit/tempmail
Requirements: PHP 8.1 or higher.
◈ Quick start
use Pyzit\TempMail\TempMailClient; $client = new TempMailClient('YOUR_API_TOKEN'); $result = $client->check('user@example.com'); if ($result->isDisposable) { echo '❌ Disposable email — rejected'; } else { echo '✅ Looks clean — allowed'; }
Get your API token at temp-mail-detector.pyzit.com.
Important: API tokens now use the prefix
pyzit_live_...(e.g.,pyzit_live_7b19e2f4a5c84d12903456789abcdef0).
Tip: Store your token in an environment variable, never hard-code it.
$client = new TempMailClient($_ENV['PYZIT_TOKEN']);
◈ API tiers & quota model
New architecture: Plans determine quota, not endpoint access. Every plan can use all endpoints.
┌─────────────────────────────────────────────────────────────────────┐
│ QUOTA MODEL │
├──────────────────┬─────────────┬──────────────────────────────────┤
│ Plan │ Simple │ Detailed │
│ │ Quota/mo │ Quota/mo │
├──────────────────┼─────────────┼──────────────────────────────────┤
│ Free Developer │ 1,000 │ 20 │
│ Pro │ 50,000 │ 1,000 │
│ Scale │ 500,000 │ 25,000 │
│ Enterprise │ Custom │ Custom │
└──────────────────┴─────────────┴──────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ BULK BATCH LIMITS │
├──────────────────┬─────────────┬──────────────────────────────────┤
│ Plan │ Max Emails │ Notes │
├──────────────────┼─────────────┼──────────────────────────────────┤
│ Free Developer │ 10 │ Per request │
│ Pro │ 50 │ Per request │
│ Scale │ 100 │ Per request │
│ Enterprise │ 500+ │ Custom configured │
└──────────────────┴─────────────┴──────────────────────────────────┘
Important:
- Unlimited API keys across all plans
- Token scopes determine access:
tmd:basic(check + bulk),tmd:detailed(detailed),tmd:*(all) - Any user on any plan can create tokens with any scope
◈ All methods
CheckResult ← check(string $email)
The fastest check. One email in, one decision out. Uses simple_quota.
$result = $client->check('user@mailnator.com'); $result->email // 'user@mailnator.com' $result->isDisposable // true $result->status // 'disposable' $result->isClean() // false (convenience method, opposite of isDisposable)
Response shape:
CheckResult
├── email string — the email you submitted
├── isDisposable bool — true = block it
├── isPrivacyRelay bool — true = recognized privacy relay
├── status string — 'clean' | 'disposable' | 'privacy_relay'
├── relayProvider ?string — provider slug (e.g. 'apple')
├── providerName ?string — provider display name
└── isClean() bool — shorthand for not isDisposable
DetailedResult ← detailed(string $email)
Full forensic analysis. DNS records (MX, A, SPF, DMARC), reputation scoring,
domain classification. Uses detailed_quota. Requires tmd:detailed scope.
$result = $client->detailed('hi@pyzit.com'); $result->riskLevel // 'low' $result->classification // 'trusted' $result->reputationScore // 100 (integer 0 to 100) $result->shouldReject() // false (convenience method) // DNS intelligence $result->hasMx() // true $result->details->hasMx // true $result->details->mxRecords // ['mail1.pyzit.com', 'mail2.pyzit.com'] $result->details->hasSpf // true $result->details->spfRecord // 'v=spf1 include:_spf.pyzit.com ~all' $result->details->hasDmarc // true $result->details->dmarcRecord // 'v=DMARC1; p=reject; sp=reject'
Response shape:
DetailedResult
├── email string
├── domain string
├── isDisposable bool
├── isTrusted bool
├── isPrivacyRelay bool
├── relayProvider ?string
├── providerName ?string
├── classification string — 'trusted' | 'clean' | 'privacy_relay' | 'suspicious' | 'disposable'
├── reputationScore int — 0 (worst) to 100 (best)
├── riskLevel string — 'low' | 'medium' | 'high'
├── isValidFormat bool
├── cached bool
├── ruleApplied ?string
├── status string — 'clean' | 'disposable' | 'privacy_relay'
├── isClean() bool — shorthand: not isDisposable
├── isHighRisk() bool — shorthand: riskLevel == 'high'
├── isTrustedDomain() bool — shorthand: isTrusted
├── shouldReject() bool — shorthand: isDisposable or not isTrusted
├── shouldFlag() bool — shorthand: classification in ('unknown', 'suspicious')
├── hasMx() bool — shorthand: details->hasMx
├── mxHostnames() array — exchange hostnames
├── aIps() array — resolved A record IPs
└── details DetailedDetails
├── hasMx bool
├── mxRecords array of string
├── hasA bool
├── aRecords array of string
├── hasSpf bool
├── spfRecord ?string
├── hasDmarc bool
└── dmarcRecord ?string
BulkResult ← bulk(array $emails)
Validate multiple emails in a single API call. Uses simple_quota. Batch size depends on your plan (Free=10, Starter=25, Pro=50, Growth=75, Scale=100).
$result = $client->bulk([ 'hi@pyzit.com', 'user@mailnator.com', 'user@privaterelay.appleid.com', ]); $result->total // 3 $result->status // 'mixed' $result->disposableCount // 1 $result->privacyRelayCount // 1 $result->flaggedDomains // ['mailnator.com'] $result->cleanEmails() // ['hi@pyzit.com', 'user@privaterelay.appleid.com'] $result->disposableEmails() // ['user@mailnator.com'] $result->privacyRelayEmails() // ['user@privaterelay.appleid.com']
Response shape:
BulkResult
├── total int — number of emails processed
├── status string — 'clean' | 'disposable' | 'privacy_relay' | 'mixed'
├── disposableCount int — number of disposable emails
├── privacyRelayCount int — number of privacy relay emails
├── flaggedDomains array — unique disposable domains
├── results array — CheckResult[]
├── cleanEmails() array — emails where isDisposable=false
├── disposableEmails() array — emails where isDisposable=true
├── privacyRelayEmails() array — emails where isPrivacyRelay=true
├── isAllClean() bool — all emails are clean
├── isAllDisposable() bool — all emails are disposable
└── isMixed() bool — mixed results
◈ Response models
All responses are fully typed with PHP 8.1+ type declarations. You get autocomplete, IDE support, and type safety.
Pyzit\TempMail\Models\
│
├── CheckResult ← client->check()
├── DetailedResult ← client->detailed()
│ └── DetailedDetails (DNS intelligence)
└── BulkResult ← client->bulk()
◈ Error handling
All SDK errors inherit from PyzitException, so you can catch everything
at one level or be specific.
PyzitException ← catch-all for any SDK error
├── AuthenticationException ← HTTP 401 — bad or missing token
├── InsufficientScopeError ← HTTP 403 — token lacks required scope
│ └── getRequiredScope() ← string, e.g. 'tmd:basic' or 'tmd:detailed'
├── QuotaExceededError ← HTTP 402 — monthly quota exhausted
│ └── getQuotaType() ← string, 'simple' or 'detailed'
├── BatchLimitExceededError ← HTTP 400 — bulk request exceeds plan limit
│ ├── getMaxAllowed() ← int, plan's batch size limit
│ └── getAttempted() ← int, emails attempted
├── ValidationError ← HTTP 400 — malformed email or request
│ └── getFieldErrors() ← array, field-specific errors
├── RateLimitException ← HTTP 429 — rate limit exceeded
│ └── getRetryAfter() ← int, seconds to wait
├── ApiException ← HTTP 5xx or unexpected status
│ ├── getStatusCode() ← int
│ └── getResponseBody() ← string, raw body for debugging
└── TimeoutException ← request took too long
Recommended pattern — catch specific errors:
use Pyzit\TempMail\TempMailClient; use Pyzit\TempMail\Exceptions\{ AuthenticationException, InsufficientScopeError, QuotaExceededError, BatchLimitExceededError, RateLimitException, ApiException, TimeoutException, PyzitException }; $client = new TempMailClient('YOUR_TOKEN'); try { $result = $client->check('user@example.com'); } catch (AuthenticationException $e) { // token is wrong — fail fast, don't retry die('Check your PYZIT_TOKEN environment variable.'); } catch (InsufficientScopeError $e) { // token lacks required scope echo "Your API token lacks the '{$e->getRequiredScope()}' scope."; } catch (QuotaExceededError $e) { // monthly quota exhausted echo "You've exceeded your monthly {$e->getQuotaType()} quota. Upgrade your plan."; } catch (BatchLimitExceededError $e) { // bulk request exceeds plan limit echo "Your plan allows max {$e->getMaxAllowed()} emails per bulk request."; } catch (RateLimitException $e) { // back off and retry sleep($e->getRetryAfter()); $result = $client->check('user@example.com'); } catch (TimeoutException $e) { // API too slow — decide how to handle in your app echo 'Pyzit API timed out — allowing email through.'; } catch (ApiException $e) { // unexpected server error echo "Unexpected error {$e->getStatusCode()}: {$e->getResponseBody()}"; } catch (PyzitException $e) { // fallback for any other SDK error echo 'Something went wrong with the Pyzit SDK.'; }
Minimal pattern — just block disposables, ignore errors gracefully:
function isAllowed(string $email): bool { try { return !$client->check($email)->isDisposable; } catch (PyzitException $e) { return true; // fail open — let the email through if API is down } }
◈ Framework integrations
Laravel
// app/Services/EmailValidator.php namespace App\Services; use Pyzit\TempMail\TempMailClient; use Pyzit\TempMail\Exceptions\PyzitException; class EmailValidator { private TempMailClient $client; public function __construct() { $this->client = new TempMailClient(env('PYZIT_TOKEN')); } public function validate(string $email): bool { try { $result = $this->client->check($email); return !$result->isDisposable; } catch (PyzitException $e) { return true; // fail open } } } // app/Http/Controllers/AuthController.php public function register(Request $request, EmailValidator $validator) { if (!$validator->validate($request->email)) { return response()->json([ 'error' => 'Disposable email addresses are not allowed.' ], 422); } // continue with registration... }
Symfony
// src/Validator/NotDisposableEmail.php namespace App\Validator; use Symfony\Component\Validator\Constraint; use Symfony\Component\Validator\ConstraintValidator; use Pyzit\TempMail\TempMailClient; use Pyzit\TempMail\Exceptions\PyzitException; class NotDisposableEmailValidator extends ConstraintValidator { private TempMailClient $client; public function __construct() { $this->client = new TempMailClient($_ENV['PYZIT_TOKEN']); } public function validate($value, Constraint $constraint): void { try { $result = $this->client->check((string)$value); if ($result->isDisposable) { $this->context->buildViolation('Disposable emails are not allowed.') ->addViolation(); } } catch (PyzitException $e) { // fail open if API is unreachable } } } // src/Validator/NotDisposableEmail.php (constraint class) namespace App\Validator; use Symfony\Component\Validator\Constraint; #[\Attribute] class NotDisposableEmail extends Constraint { public string $message = 'Disposable email addresses are not allowed.'; }
WordPress
// functions.php require_once __DIR__ . '/vendor/autoload.php'; use Pyzit\TempMail\TempMailClient; use Pyzit\TempMail\Exceptions\PyzitException; function validate_disposable_email($email) { $client = new TempMailClient(getenv('PYZIT_TOKEN')); try { $result = $client->check($email); return !$result->isDisposable; } catch (PyzitException $e) { return true; // fail open } } add_filter('registration_errors', function($errors, $sanitized_user_login, $user_email) { if (!validate_disposable_email($user_email)) { $errors->add('disposable_email', 'Disposable email addresses are not allowed.'); } return $errors; }, 10, 3);
◈ Configuration
TempMailClient accepts the following options:
$client = new TempMailClient( apiKey: 'YOUR_TOKEN', // required baseUrl: 'https://api.pyzit.com', // override for testing timeout: 5, // seconds, default 5 maxRetries: 2, // retry attempts for 429/5xx, default 2 failOpen: false, // return clean on network errors, default false );
| Parameter | Type | Default | Description |
|---|---|---|---|
apiKey |
string |
— | Your Pyzit API token (required) |
baseUrl |
string |
https://api.pyzit.com |
Override for local testing / mocks |
timeout |
int |
5 |
Request timeout in seconds |
maxRetries |
int |
2 |
Retry attempts for 429/5xx errors |
failOpen |
bool |
false |
Return clean result on network errors |
◈ Development
This project uses standard PHP tooling.
# clone git clone https://github.com/pyzit-org/temp-mail-detector-sdk-php.git cd temp-mail-detector-sdk-php # install dependencies composer install # run tests (no real API calls — all HTTP is mocked) vendor/bin/phpunit # tests with Docker (recommended for local development) docker compose up docker compose run --rm sdk vendor/bin/phpunit # code style check vendor/bin/phpcs --standard=PSR12 src/
Project layout:
src/
├── Exceptions/
│ ├── PyzitException.php ← base exception class
│ ├── AuthenticationException.php
│ ├── InsufficientScopeError.php
│ ├── QuotaExceededError.php
│ ├── BatchLimitExceededError.php
│ ├── ValidationError.php
│ ├── RateLimitException.php
│ ├── ApiException.php
│ ├── TimeoutException.php
│ ├── ScopeException.php
│ └── PlanRequiredException.php
├── Models/
│ ├── CheckResult.php
│ ├── DetailedResult.php
│ ├── DetailedDetails.php
│ ├── ReputationDetail.php
│ ├── Signals.php
│ ├── DnsIntelligence.php
│ ├── MxRecord.php
│ ├── StabilityInfo.php
│ └── BulkResult.php
├── HttpClient.php ← internal HTTP layer
└── TempMailClient.php ← public API surface
tests/
├── ExceptionsTest.php
├── HttpClientErrorTest.php
├── ModelsTest.php
├── TempMailClientTest.php
└── Fixtures.php ← shared test data
◈ Changelog
See CHANGELOG.md.
◈ License
Built with care by the Pyzit team · https://pyzit.com