EmailGuard SDK Guide: TypeScript, Go, Python, PHP, and Ruby

by EmailGuard Engineering

August 11, 2026engineering4 min read

Share this article

Enjoyed this article?

More notes on building products, infrastructure, and teams.

EmailGuard ships official SDKs for TypeScript/JavaScript, Go, Python, PHP, and Ruby—generated from the public OpenAPI spec so every client stays aligned with /api/v1. This walkthrough installs each SDK, authenticates with a team API key, and runs the same email detect call you would use at signup.

Deeper per-language pages live under the API reference:

For product context (what to block and why), see the email validation API checklist and disposable blocking at signup.

Before you start

Create a team-scoped API key in Settings → API keys with at least the email:detect scope (scopes explained).
Prefer Authorization: Bearer egsk_live_... (SDKs set this from EMAILGUARD_API_KEY).
Never ship the key in a browser bundle—call EmailGuard from your backend or edge function.

Endpoint used below: Detect email characteristics (GET /api/v1/emails/detect).

The TypeScript client unwraps the JSON envelope and returns data directly. The OpenAPI-generated Go, Python, PHP, and Ruby clients return the full envelope (code / data / message)—read data before branching.

TypeScript / JavaScript (`@emailguard/sdk`)

npm install @emailguard/sdk
# or: pnpm add @emailguard/sdk

import { createPublicClient, loadConfig } from "@emailguard/sdk";
 
const client = createPublicClient(loadConfig()); // reads EMAILGUARD_API_KEY
const data = await client.detectEmailCharacteristics({
  email: "user@example.com",
});
 
if (!data?.syntax_validation) {
  throw new Error("Invalid email syntax");
}
if (data.disposable) {
  throw new Error("Disposable email addresses are not allowed");
}
// Optional policy: data.relay_domain, data.public_domain, data.detection_source

Full guide: TypeScript SDK.

Go (`github.com/EmailGuard/emailguard-go`)

go get github.com/EmailGuard/emailguard-go

package main
 
import (
	"context"
	"fmt"
	"os"
 
	openapiclient "github.com/EmailGuard/emailguard-go"
)
 
func main() {
	ctx := context.Background()
	configuration := openapiclient.NewConfiguration()
	configuration.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("EMAILGUARD_API_KEY"))
	apiClient := openapiclient.NewAPIClient(configuration)
 
	result, _, err := apiClient.EmailAPI.ApiV1EmailsDetectGet(ctx).
		Email("user@example.com").
		Execute()
	if err != nil {
		fmt.Fprintf(os.Stderr, "request failed: %v\n", err)
		os.Exit(1)
	}
 
	data := result.GetData()
	if data.GetDisposable() {
		fmt.Println("reject: disposable")
	}
}

Full guide: Go SDK.

Python (`emailguard_sdk`)

pip install emailguard_sdk

import os
import emailguard_sdk
from emailguard_sdk.rest import ApiException
 
configuration = emailguard_sdk.Configuration(
    host="https://api.emailguard.co",
)
configuration.api_key["Authorization"] = os.environ["EMAILGUARD_API_KEY"]
configuration.api_key_prefix["Authorization"] = "Bearer"
 
with emailguard_sdk.ApiClient(configuration) as api_client:
    api = emailguard_sdk.EmailApi(api_client)
    try:
        result = api.api_v1_emails_detect_get(email="user@example.com")
    except ApiException as e:
        raise SystemExit(e) from e
 
    data = result.data
    if data and data.disposable:
        raise SystemExit("Disposable email addresses are not allowed")

Full guide: Python SDK.

PHP (`emailguard/emailguard-sdk`)

composer require emailguard/emailguard-sdk

<?php
 
use emailguardSdk\Api\EmailApi;
use emailguardSdk\ApiException;
use emailguardSdk\Configuration;
 
require __DIR__ . '/vendor/autoload.php';
 
Configuration::getDefaultConfiguration()
    ->setHost('https://api.emailguard.co')
    ->setApiKey('Authorization', getenv('EMAILGUARD_API_KEY'))
    ->setApiKeyPrefix('Authorization', 'Bearer');
 
$api = new EmailApi();
 
try {
    $result = $api->apiV1EmailsDetectGet('user@example.com');
} catch (ApiException $e) {
    throw new RuntimeException($e->getResponseBody() ?: $e->getMessage(), $e->getCode(), $e);
}
 
$data = $result->getData();
if ($data && $data->getDisposable()) {
    throw new RuntimeException('Disposable email addresses are not allowed');
}

Full guide: PHP SDK.

Ruby (`emailguard_sdk`)

gem install emailguard_sdk
# or add to Gemfile: gem "emailguard_sdk"

require "emailguard_sdk"
 
Emailguard.configure do |config|
  config.host = "https://api.emailguard.co"
  config.api_key["Authorization"] = ENV.fetch("EMAILGUARD_API_KEY")
  config.api_key_prefix["Authorization"] = "Bearer"
end
 
api = Emailguard::EmailApi.new
result = api.api_v1_emails_detect_get("user@example.com")
data = result.data
 
if data&.disposable
  raise "Disposable email addresses are not allowed"
end

Full guide: Ruby SDK.

Shared response fields to branch on

Field	Typical signup use
`syntax_validation`	Reject garbage early
`disposable`	Hard block throwaways (why lists alone fail)
`detection_source`	Log `precomputed` vs `live_dns`
`relay_domain` / `relay_provider`	Allow by default; step-up if needed (relays vs disposables)
`public_domain`	Analytics / corporate-only policies
`normalized`	Deduplicate aliases when you enable normalize

Field reference: disposable detection, relay detection, email detection overview.

MCP server (AI agents)

If you wire EmailGuard into an MCP-capable agent (Cursor, Claude Desktop, custom hosts), use the MCP integration guide instead of pasting curl into tool definitions. Package: @emailguard/mcp. Same API surface; agent-friendly tool schemas.

Zapier and no-code

Zapier and other automation hosts can call the HTTP API with your key when you do not want a language SDK. Prefer an official SDK in app backends for typed errors and OpenAPI alignment. Overview: getting started.

Error handling checklist

401 / 403 — Wrong key or missing email:detect scope.
429 — Back off; honor Retry-After (API rate limiting).
5xx / network — Fail open on signup (allow + alert) unless your risk model requires fail closed.
Timeouts — Keep signup SLOs in mind; most detect calls resolve from precomputed data.

Next steps

Open the API playground and run detect once with your key.
Copy the reject path from block disposable emails at signup.
Compare plans on pricing when you leave local testing.