Search by

pyzit / tempmail

pyzit

Official PHP SDK for the Pyzit disposable email detector API

1.0.0 2026-11-07 18:26 UTC

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.

Latest Stable Version PHP Version License Type Safety

◈ 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

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

MIT © Pyzit

Built with care by the Pyzit team · https://pyzit.com