Official SDKs

EmailKind provides official SDKs for Python, Node.js, and Go. They handle authentication, error handling, rate limits, and provide typed responses.

Python

View on PyPI

Installation

pip install emailkind

Quick start

from emailkind import EmailKind

client = EmailKind("sk_live_YOUR_KEY")

# Classify an email
result = client.classify(email="[email protected]")
print(result.provider.name)           # "Google Workspace"
print(result.classification.is_business)  # True

# Classify with company enrichment
result = client.classify(domain="stripe.com", enrich=True)
print(result.company.name)  # "Stripe, Inc"

Batch classification

batch = client.classify_batch(
    emails=["[email protected]", "[email protected]"],
    enrich=True
)
for item in batch.results:
    print(f"{item.domain}: {item.provider.type}")

Custom rules

# Create a rule
rule = client.create_rule(
    match_type="domain",
    match_value="internal.company.com",
    provider_name="Internal Mail",
    provider_type="business"
)

# List rules
rules = client.list_rules()

# Delete a rule
client.delete_rule(rule.id)

Bulk processing

# Upload a CSV
job = client.bulk_upload("emails.csv", enrich=True)
print(job.id)  # "550e8400-..."

# Check status
job = client.bulk_status(job.id)
print(f"{job.processed_items}/{job.total_items}")

# Download results
csv_data = client.bulk_results(job.id)
with open("results.csv", "wb") as f:
    f.write(csv_data)

Error handling

from emailkind import EmailKind, RateLimitError, AuthenticationError

client = EmailKind("sk_live_YOUR_KEY")

try:
    result = client.classify(email="[email protected]")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry in {e.retry_after}s")

Configuration

# API key from environment variable
client = EmailKind()  # reads EMAILKIND_API_KEY

# Custom base URL
client = EmailKind("sk_live_xxx", base_url="https://custom.endpoint.com")

# Custom timeout (seconds)
client = EmailKind("sk_live_xxx", timeout=10)

Node.js

View on npm

Installation

npm install emailkind

Quick start

import EmailKind from 'emailkind';

const client = new EmailKind('sk_live_YOUR_KEY');

// Classify an email
const result = await client.classify({ email: '[email protected]' });
console.log(result.provider.name);            // "Google Workspace"
console.log(result.classification.is_business); // true

// With enrichment
const enriched = await client.classify({ domain: 'stripe.com', enrich: true });
console.log(enriched.company?.name); // "Stripe, Inc"

Batch classification

const batch = await client.classifyBatch({
  emails: ['[email protected]', '[email protected]'],
  enrich: true,
});

for (const item of batch.results) {
  console.log(`${item.domain}: ${item.provider?.type}`);
}

Custom rules

const rule = await client.createRule({
  matchType: 'domain',
  matchValue: 'internal.company.com',
  providerName: 'Internal Mail',
  providerType: 'business',
});

const rules = await client.listRules();
await client.deleteRule(rule.id);

Bulk processing

const job = await client.bulkUpload('emails.csv', { enrich: true });
const status = await client.bulkStatus(job.id);
const csv = await client.bulkResults(job.id); // Buffer

Error handling

import EmailKind, { RateLimitError, AuthenticationError } from 'emailkind';

try {
  const result = await client.classify({ email: '[email protected]' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry in ${err.retryAfter}s`);
  }
}

Go

View on pkg.go.dev

Installation

go get github.com/gastonmedia/emailkind-go

Quick start

package main

import (
    "context"
    "fmt"
    emailkind "github.com/gastonmedia/emailkind-go"
)

func main() {
    client := emailkind.NewClient("sk_live_YOUR_KEY")
    ctx := context.Background()

    // Classify an email
    result, err := client.Classify(ctx, &emailkind.ClassifyParams{
        Email: "[email protected]",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Provider.Name)            // "Google Workspace"
    fmt.Println(result.Classification.IsBusiness) // true

    // With enrichment
    result, _ = client.Classify(ctx, &emailkind.ClassifyParams{
        Domain: "stripe.com",
        Enrich: true,
    })
    if result.Company != nil {
        fmt.Println(result.Company.Name) // "Stripe, Inc"
    }
}

Batch classification

batch, err := client.ClassifyBatch(ctx, &emailkind.BatchParams{
    Emails: []string{"[email protected]", "[email protected]"},
    Enrich: true,
})
for _, item := range batch.Results {
    fmt.Printf("%s: %s\n", item.Domain, item.Provider.Type)
}

Custom rules

rule, _ := client.CreateRule(ctx, &emailkind.CreateRuleParams{
    MatchType:    "domain",
    MatchValue:   "internal.company.com",
    ProviderName: "Internal Mail",
    ProviderType: "business",
})

rules, _ := client.ListRules(ctx)
client.DeleteRule(ctx, rule.ID)

Bulk processing

job, _ := client.BulkUpload(ctx, "emails.csv", &emailkind.BulkUploadParams{Enrich: true})
status, _ := client.BulkStatus(ctx, job.ID)
csvData, _ := client.BulkResults(ctx, job.ID)
os.WriteFile("results.csv", csvData, 0644)

Error handling

result, err := client.Classify(ctx, &emailkind.ClassifyParams{Email: "[email protected]"})
if err != nil {
    if emailkind.IsAuthError(err) {
        log.Fatal("Invalid API key")
    }
    if emailkind.IsRateLimitError(err) {
        retryAfter := emailkind.RetryAfter(err)
        log.Printf("Rate limited. Retry in %ds", retryAfter)
    }
}

Configuration

// Custom timeout
client := emailkind.NewClient("sk_live_xxx",
    emailkind.WithTimeout(10 * time.Second),
)

// Custom base URL
client := emailkind.NewClient("sk_live_xxx",
    emailkind.WithBaseURL("https://custom.endpoint.com"),
)

Feature comparison

| Feature | Python | Node.js | Go | |---|---|---|---| | Classify | classify() | classify() | Classify() | | Batch | classify_batch() | classifyBatch() | ClassifyBatch() | | Custom rules | list_rules(), create_rule(), delete_rule() | listRules(), createRule(), deleteRule() | ListRules(), CreateRule(), DeleteRule() | | Bulk upload | bulk_upload() | bulkUpload() | BulkUpload() | | Bulk status | bulk_status() | bulkStatus() | BulkStatus() | | Bulk results | bulk_results() | bulkResults() | BulkResults() | | Typed responses | Dataclasses | TypeScript interfaces | Structs | | Error types | Exception classes | Error subclasses | Sentinel functions | | Rate limit retry | retry_after field | retryAfter field | RetryAfter() helper | | Dependencies | requests | None (native fetch) | None (stdlib) | | Min version | Python 3.8+ | Node.js 18+ | Go 1.22+ |