README

EvilMail PHP SDK

Official PHP client library for the EvilMail disposable email API

Installation • Quick Start • API Reference • Error Handling • Documentation

The EvilMail PHP SDK provides a clean, type-safe interface for integrating temporary email, disposable email addresses, email verification, inbox management, and custom domain email services into your PHP applications. Built for PHP 8.1+ with full PSR-12 compliance.

Features

• Temporary Email — Create anonymous disposable email addresses with configurable TTL
• Email Verification Codes — Automatically extract OTP codes from Google, Facebook, Instagram, TikTok, Discord, Twitter, LinkedIn, iCloud
• Account Management — Create, delete, and manage persistent email accounts on custom domains
• Inbox Access — Read emails, list messages, fetch full message content (HTML & plain text)
• Random Email Generator — Batch create random email accounts with auto-generated passwords
• Domain Management — List free, premium, and custom email domains
• Shortlink Creation — Generate short URLs for temporary email sessions
• Temp Email Messages — Read individual messages from temporary email sessions
• Typed Exceptions — Granular error handling with dedicated exception classes
• Guzzle Powered — Built on Guzzle HTTP for reliable, configurable HTTP transport

Requirements

• PHP 8.1 or later
• Guzzle 7.5+
• An EvilMail API key — Get yours free

Installation

Install via Composer:

composer require evilmail/evilmail-php

Quick Start

<?php

require 'vendor/autoload.php';

use EvilMail\Client;

$client = new Client('your-api-key');

// Create a temporary disposable email address
$temp = $client->tempEmail->create('evilmail.pro', 60);
echo "Temporary email: " . $temp['email'] . "\n";
echo "Session token: " . $temp['sessionToken'] . "\n";

// Check session status and retrieve messages
$session = $client->tempEmail->getSession($temp['sessionToken']);
echo "Expires at: " . $session['expiresAt'] . "\n";

// Read a specific message from temp email inbox
$message = $client->messages->read($temp['sessionToken'], 1);
echo "Subject: " . $message['subject'] . "\n";

// Extract a Google verification code from any email
$code = $client->verification->getCode('google', 'user@yourdomain.com');
echo "Verification code: " . $code['code'] . "\n";

// List all email accounts
$accounts = $client->accounts->list();

// Batch create random email accounts
$batch = $client->randomEmail->create('yourdomain.com', 5, 16);
echo "Created " . $batch['count'] . " random accounts\n";

Configuration

// Basic initialization
$client = new Client('your-api-key');

// Custom base URL (self-hosted instances)
$client = new Client('your-api-key', 'https://your-instance.example.com');

// Advanced Guzzle configuration (proxy, timeout, SSL)
$client = new Client('your-api-key', null, [
    'timeout' => 60,
    'proxy' => 'tcp://localhost:8080',
    'verify' => '/path/to/ca-bundle.crt',
]);

API Reference

Temporary Email

Create anonymous, disposable email addresses with automatic expiration. Perfect for sign-up verification, testing, and privacy protection.

Create Temporary Email

$temp = $client->tempEmail->create(?string $domain, ?int $ttlMinutes);

Returns: ['email', 'domain', 'sessionToken', 'ttlMinutes', 'expiresAt']

Get Session Status

$session = $client->tempEmail->getSession(string $token);

Check if a temporary email session is still active and get session details.

Delete Temporary Email

$client->tempEmail->delete(string $token);

Permanently delete a temporary email session and all associated messages.

Temp Email Messages

Read individual messages from temporary email sessions using the session token.

Read Message

$message = $client->messages->read(string $token, int $uid);

Returns: ['uid', 'from', 'subject', 'text', 'html', 'date', 'seen']

Accounts

Manage persistent email accounts on your custom domains. Full CRUD operations for email account lifecycle management.

List Accounts

$accounts = $client->accounts->list();

Returns: Array of ['email', 'domain', 'createdAt'] objects.

Create Account

$account = $client->accounts->create(string $email, string $password);

Delete Accounts

$result = $client->accounts->delete(array $emails);

Returns: ['deletedCount' => 2]

Change Password

$client->accounts->changePassword(string $email, string $newPassword);

Inbox & Messages

Read emails from persistent account inboxes. Access full message content including HTML, plain text, headers, and metadata.

List Inbox Messages

$messages = $client->inbox->list(string $email);

Returns: Array of ['uid', 'from', 'subject', 'date', 'seen'] objects.

Read Full Message

$message = $client->inbox->read(int $uid, string $email);

Returns: ['uid', 'from', 'subject', 'text', 'html', 'date', 'seen']

Verification Codes

Automatically extract OTP verification codes from emails sent by popular services. Supports regex-based code extraction for accurate results.

$code = $client->verification->getCode(string $service, string $email);

Supported services: facebook, twitter, google, icloud, instagram, tiktok, discord, linkedin

Returns: ['code', 'service', 'email', 'from', 'subject', 'date']

List Supported Services

$services = \EvilMail\Resources\Verification::supportedServices();

Random Email Generator

Generate random email accounts with auto-generated usernames and secure passwords. Ideal for bulk account creation and testing.

Preview Random Email

$preview = $client->randomEmail->preview(?int $passwordLength);

Returns: ['username', 'email', 'password', 'domain']

Batch Create Random Emails

$batch = $client->randomEmail->create(string $domain, ?int $count, ?int $passwordLength);

Returns: ['count', 'emails' => [['email', 'password', 'note?'], ...]]

Domains

List available email domains grouped by tier — free domains, premium domains, and your custom domains.

List Customer Domains

$domains = $client->domains->list();

Returns: ['free', 'premium', 'customer', 'packageType', 'authenticated']

List Public Domains

$publicDomains = $client->domains->listPublic();

Returns all publicly available domains (no authentication required).

Shortlinks

Generate short URLs for temporary email sessions, useful for sharing or bookmarking.

$link = $client->shortlink->create(string $token, string $type);

Returns: ['shortUrl', 'code']

Error Handling

The SDK provides granular exception handling with typed exception classes for every error scenario:

use EvilMail\Exceptions\AuthenticationException;
use EvilMail\Exceptions\NotFoundException;
use EvilMail\Exceptions\RateLimitException;
use EvilMail\Exceptions\ValidationException;
use EvilMail\Exceptions\EvilMailException;

try {
    $code = $client->verification->getCode('google', 'user@yourdomain.com');
    echo "Your code: " . $code['code'];
} catch (AuthenticationException $e) {
    echo "Invalid API key: " . $e->getMessage();
} catch (NotFoundException $e) {
    echo "No verification email found yet";
} catch (RateLimitException $e) {
    echo "Rate limited — retry after " . $e->getRetryAfter() . " seconds";
} catch (ValidationException $e) {
    print_r($e->getErrors());
} catch (EvilMailException $e) {
    echo "API error [{$e->getStatusCode()}]: " . $e->getMessage();
}

Use Cases

• Automated Testing — Generate disposable email addresses for end-to-end test suites
• Sign-up Verification — Create temp emails and extract verification codes automatically
• Email Account Provisioning — Bulk create and manage email accounts via API
• Privacy Protection — Use anonymous email addresses to protect user identity
• Bot & Automation Workflows — Integrate email capabilities into PHP scripts and cron jobs
• SaaS Onboarding Flows — Automate email verification during user registration
• QA & Staging Environments — Isolate email testing without polluting real inboxes

Related SDKs

Links

• EvilMail Website — Temporary & custom domain email platform
• API Documentation — Full REST API reference
• Chrome Extension — Disposable temp email in your browser
• Firefox Add-on — Temp email for Firefox
• Mobile App — Privacy-first email on Android

License

This SDK is released under the MIT License.

Support

• Issues: github.com/Evil-Mail/evilmail-php/issues
• Email: support@evilmail.pro
• Website: evilmail.pro