Official Go client library for the EvilMail disposable email API
Installation • Quick Start • API Reference • Error Handling • Documentation
The EvilMail Go SDK provides a clean, idiomatic Go interface for integrating temporary email, disposable email addresses, email verification code extraction, inbox management, and custom domain email services into your Go applications. Zero external dependencies — built entirely on the Go standard library.
- Zero Dependencies — Built on
net/httpand the Go standard library only - Temporary Email — Create anonymous disposable email addresses with configurable TTL
- Email Verification Codes — Auto-extract OTP codes from Google, Facebook, Instagram, TikTok, Discord, Twitter, LinkedIn, iCloud
- Account Management — Full CRUD for persistent email accounts on custom domains
- Inbox Access — Read emails, list messages, fetch full HTML & plain text content
- 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
- Context Support — Full
context.Contextpropagation for cancellation and deadlines - Functional Options — Clean, extensible client configuration pattern
- Typed Errors — Structured error types with
errors.As/errors.Issupport - Thread Safe — Safe for concurrent use from multiple goroutines
- Go 1.21 or later
- An EvilMail API key — Get yours free
go get github.com/Evil-Mail/evilmail-gopackage main
import (
"context"
"fmt"
"log"
evilmail "github.com/Evil-Mail/evilmail-go"
)
func main() {
client := evilmail.New("your-api-key")
ctx := context.Background()
// Create a temporary disposable email address
temp, err := client.TempEmail.Create(ctx, &evilmail.CreateTempEmailRequest{
Domain: "evilmail.pro",
TTLMinutes: 60,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Temporary email: %s\n", temp.Email)
fmt.Printf("Session token: %s\n", temp.SessionToken)
// Check session status
session, err := client.TempEmail.GetSession(ctx, temp.SessionToken)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Expires at: %s\n", session.ExpiresAt)
// Read a specific message from temp inbox
msg, err := client.TempEmail.GetMessage(ctx, temp.SessionToken, 1)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Subject: %s\n", msg.Subject)
// Extract a Google verification code
code, err := client.Verification.GetCode(ctx, evilmail.ServiceGoogle, "[email protected]")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Verification code: %s\n", code.Code)
// List all accounts
accounts, err := client.Accounts.List(ctx)
if err != nil {
log.Fatal(err)
}
for _, acct := range accounts {
fmt.Printf("Account: %s\n", acct.Email)
}
// Batch create random email accounts
batch, err := client.RandomEmail.BatchCreate(ctx, &evilmail.BatchCreateRandomEmailRequest{
Domain: "yourdomain.com",
Count: 5,
PasswordLength: 20,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created %d random accounts\n", batch.Count)
}The client uses the functional options pattern for clean, extensible configuration:
import "time"
// Default configuration
client := evilmail.New("your-api-key")
// Custom configuration
client := evilmail.New("your-api-key",
evilmail.WithBaseURL("https://your-instance.example.com"),
evilmail.WithTimeout(60 * time.Second),
evilmail.WithHTTPClient(myCustomHTTPClient),
)| Option | Description |
|---|---|
WithBaseURL(url) |
Override the default API base URL |
WithTimeout(d) |
Set HTTP request timeout (default: 30s) |
WithHTTPClient(c) |
Provide a custom *http.Client |
All methods accept a context.Context as their first argument for cancellation, deadlines, and tracing propagation.
Create anonymous, disposable email addresses with automatic expiration. Ideal for sign-up verification, testing, and privacy protection.
temp, err := client.TempEmail.Create(ctx, &evilmail.CreateTempEmailRequest{
Domain: "evilmail.pro", // optional
TTLMinutes: 30, // optional, minutes until auto-expiry
})Returns: *TempEmail — Email, Domain, SessionToken, TTLMinutes, ExpiresAt
session, err := client.TempEmail.GetSession(ctx, token)Check if a temporary email session is still active and retrieve session details.
msg, err := client.TempEmail.GetMessage(ctx, token, uid)Read a specific message from a temporary email inbox.
err := client.TempEmail.Delete(ctx, token)Permanently delete a temporary email session and all associated data.
Manage persistent email accounts on custom domains.
// List all accounts
accounts, err := client.Accounts.List(ctx)
// Create a new account
resp, err := client.Accounts.Create(ctx, &evilmail.CreateAccountRequest{
Email: "[email protected]",
Password: "secure-password",
})
// Delete accounts
deleted, err := client.Accounts.Delete(ctx, &evilmail.DeleteAccountsRequest{
Emails: []string{"[email protected]"},
})
// Change password
err = client.Accounts.ChangePassword(ctx, &evilmail.ChangePasswordRequest{
Email: "[email protected]",
NewPassword: "new-secure-password",
})Read emails from persistent account inboxes with full message content.
// List inbox messages
messages, err := client.Inbox.List(ctx, "[email protected]")
for _, msg := range messages {
fmt.Printf("[%d] %s: %s\n", msg.UID, msg.From, msg.Subject)
}
// Read full message content (HTML + plain text)
msg, err := client.Inbox.GetMessage(ctx, 12345, "[email protected]")
fmt.Printf("HTML: %s\nText: %s\n", msg.HTML, msg.Text)Automatically extract OTP verification codes from emails sent by popular services.
code, err := client.Verification.GetCode(ctx, evilmail.ServiceGoogle, "[email protected]")
fmt.Printf("Code: %s (from: %s)\n", code.Code, code.From)Supported services:
| Constant | Service |
|---|---|
ServiceFacebook |
|
ServiceTwitter |
Twitter / X |
ServiceGoogle |
|
ServiceICloud |
iCloud |
ServiceInstagram |
|
ServiceTikTok |
TikTok |
ServiceDiscord |
Discord |
ServiceLinkedIn |
Generate random email accounts with secure auto-generated credentials.
// Preview a random email (without creating it)
preview, err := client.RandomEmail.Preview(ctx)
fmt.Printf("%s : %s\n", preview.Email, preview.Password)
// Batch create random email accounts
batch, err := client.RandomEmail.BatchCreate(ctx, &evilmail.BatchCreateRandomEmailRequest{
Domain: "yourdomain.com",
Count: 10,
PasswordLength: 20,
})
for _, cred := range batch.Emails {
fmt.Printf("%s : %s\n", cred.Email, cred.Password)
}List available email domains by tier.
// List customer domains (authenticated)
domains, err := client.Domains.List(ctx)
fmt.Println("Free:", domains.Free)
fmt.Println("Premium:", domains.Premium)
fmt.Println("Custom:", domains.Customer)
// List public domains (unauthenticated)
public, err := client.PublicDomains.List(ctx)
fmt.Println("Domains:", public.Domains)Generate short URLs for temporary email sessions.
link, err := client.Shortlinks.Create(ctx, &evilmail.ShortlinkRequest{
Token: sessionToken,
Type: "session",
})
fmt.Printf("Short URL: %s\n", link.ShortURL)The SDK provides typed errors compatible with Go's errors.As and errors.Is patterns:
import "errors"
msg, err := client.Inbox.GetMessage(ctx, uid, email)
if err != nil {
// Check for specific API errors
if evilmail.IsNotFoundError(err) {
fmt.Println("Message not found")
return
}
if evilmail.IsAuthError(err) {
fmt.Println("Invalid API key — check your credentials")
return
}
if evilmail.IsRateLimitError(err) {
fmt.Println("Rate limited — slow down and retry")
return
}
// Generic API error with status code
var apiErr *evilmail.APIError
if errors.As(err, &apiErr) {
fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
return
}
// Client-side validation error
var valErr *evilmail.ValidationError
if errors.As(err, &valErr) {
fmt.Printf("Invalid parameter %s: %s\n", valErr.Field, valErr.Message)
return
}
// Network or other error
log.Fatal(err)
}| Type | Description |
|---|---|
*APIError |
Non-2xx API response with StatusCode, Status, Message, Body |
*AuthError |
401/403 — wraps *APIError for authentication failures |
*ValidationError |
Client-side validation with Field and Message |
| Function | Description |
|---|---|
IsNotFoundError(err) |
Returns true for 404 responses |
IsAuthError(err) |
Returns true for 401/403 responses |
IsRateLimitError(err) |
Returns true for 429 responses |
Every method accepts context.Context for cancellation, deadlines, and distributed tracing:
// With timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
messages, err := client.Inbox.List(ctx, "[email protected]")
// With cancellation
ctx, cancel := context.WithCancel(context.Background())
go func() {
<-sigChan
cancel()
}()
temp, err := client.TempEmail.Create(ctx, nil)- Automated Testing — Generate disposable email addresses for end-to-end test suites
- Web Scraping & Crawling — Create temp emails for sign-up verification in automation pipelines
- Email Verification Bots — Automatically extract OTP codes from Google, Facebook, Instagram, and more
- Microservices — Lightweight email client for Go microservices and serverless functions
- CLI Tools — Build email automation scripts and command-line utilities
- DevOps & CI/CD — Integrate email testing into CI pipelines (GitHub Actions, GitLab CI)
- SaaS Backend — Automate email provisioning and verification in your Go backend
- Privacy & Anonymity — Use anonymous temporary email for privacy-sensitive workflows
- Kubernetes & Cloud Native — Thread-safe, context-aware client for cloud-native applications
| Language | Package | Repository |
|---|---|---|
| Node.js | evilmail |
Evil-Mail/evilmail-node |
| PHP | evilmail/evilmail-php |
Evil-Mail/evilmail-php |
| Python | evilmail |
Evil-Mail/evilmail-python |
| Go | evilmail-go |
Evil-Mail/evilmail-go |
- 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
- Issues: github.com/Evil-Mail/evilmail-go/issues
- Email: [email protected]
- Website: evilmail.pro