@zytehub/email-client

Professional email API client for Platform Services

Send emails, manage domains, and configure email infrastructure with a simple, elegant API.

Features

✅ Send Emails - Transactional emails via SendGrid/Mailgun
✅ Domain Management - Create and verify email sending domains
✅ Webhook Configuration - Auto-configure delivery tracking
✅ TypeScript Support - Full type definitions included
✅ Zero Dependencies - Lightweight and fast
✅ Promise-based API - Modern async/await support

Installation

npm install @zytehub/email-client

Quick Start

const EmailClient = require('@zytehub/email-client');

// Initialize client
const client = new EmailClient({
  apiUrl: 'https://your-platform-services.com',
  apiKey: 'your-api-key',
  platformId: 'your-platform-id'
});

// Send an email
await client.send({
  to: '[email protected]',
  subject: 'Welcome!',
  html: '<h1>Hello World</h1>',
  from_name: 'My App'
});

API Documentation

Initialize Client

const client = new EmailClient({
  apiUrl: 'https://api.yourservice.com',
  apiKey: 'sk_live_...',
  platformId: 'platform_123',
  timeout: 30000  // Optional, defaults to 30 seconds
});

Send Email

const result = await client.send({
  to: '[email protected]',
  subject: 'Your Subject',
  html: '<p>HTML content</p>',        // Optional
  text: 'Plain text content',         // Optional
  from_email: '[email protected]',   // Optional
  from_name: 'My App',                // Optional
  reply_to: '[email protected]'     // Optional
});

console.log(result.message_id); // Email sent successfully

Domain Management

Create Domain

const domain = await client.domains.create({
  provider: 'sendgrid',           // or 'mailgun'
  root_domain: 'example.com',
  subdomain: 'mail'               // Optional, creates mail.example.com
});

console.log(domain.dns_records);  // DNS records to add

Verify Domain

const verification = await client.domains.verify({
  provider: 'sendgrid',
  domain_id: '12345'
});

if (verification.verified) {
  console.log('✅ Domain verified!');
} else {
  console.log('❌ DNS records not found yet');
}

Get Domain Pool

const pool = await client.domains.getPool();
console.log(pool.domains);  // List of configured domains

Add Domain to Pool

await client.domains.addToPool({
  domain_id: 'custom_id',
  domain: 'mail.example.com',
  from_email: '[email protected]',
  provider: 'sendgrid',
  api_key: 'SG.xxx',
  active: true
});

Remove Domain

await client.domains.removeFromPool('domain_id');

Toggle Domain Status

await client.domains.toggle('domain_id', false);  // Deactivate
await client.domains.toggle('domain_id', true);   // Activate

Webhook Configuration

const result = await client.webhooks.configure({
  provider: 'mailgun',
  domain: 'mail.example.com',
  webhook_url: 'https://your-app.com/webhooks/email'
});

console.log(result.configured_events);  // ['delivered', 'failed', 'opened', ...]

Metrics (Admin Only)

// Get component metrics
const metrics = await client.metrics.get();
console.log(metrics.total_emails_sent);
console.log(metrics.delivery_rate);

// Get platform usage
const usage = await client.metrics.platforms();

// Get health status
const health = await client.metrics.health();

Error Handling

try {
  await client.send({
    to: 'invalid-email',
    subject: 'Test'
  });
} catch (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.status);        // HTTP status code
  console.error('Response:', error.response);    // API response
}

TypeScript Support

import EmailClient, { EmailClientConfig, SendEmailOptions } from '@zytehub/email-client';

const config: EmailClientConfig = {
  apiUrl: 'https://api.example.com',
  apiKey: 'sk_live_...',
  platformId: 'platform_123'
};

const client = new EmailClient(config);

const emailOptions: SendEmailOptions = {
  to: '[email protected]',
  subject: 'Welcome',
  html: '<h1>Hello</h1>'
};

await client.send(emailOptions);

Environment Variables

# Recommended: Store credentials in environment variables
EMAIL_API_URL=https://your-service.com
EMAIL_API_KEY=sk_live_your_key_here
EMAIL_PLATFORM_ID=platform_123

const client = new EmailClient({
  apiUrl: process.env.EMAIL_API_URL,
  apiKey: process.env.EMAIL_API_KEY,
  platformId: process.env.EMAIL_PLATFORM_ID
});

Use Cases

Transactional Emails

// Welcome email
await client.send({
  to: user.email,
  subject: 'Welcome to Our App!',
  html: welcomeEmailTemplate(user),
  from_name: 'Our App Team'
});

// Password reset
await client.send({
  to: user.email,
  subject: 'Reset Your Password',
  html: resetPasswordTemplate(resetToken),
  reply_to: '[email protected]'
});

Domain Setup Workflow

// 1. Create domain
const domain = await client.domains.create({
  provider: 'sendgrid',
  root_domain: 'mycompany.com',
  subdomain: 'mail'
});

// 2. Show DNS records to user
console.log('Add these DNS records:');
domain.dns_records.forEach(record => {
  console.log(`${record.type} ${record.host} → ${record.value}`);
});

// 3. Wait for DNS propagation (user adds records)
// ... user adds records ...

// 4. Verify domain
const verification = await client.domains.verify({
  provider: 'sendgrid',
  domain_id: domain.domain_id
});

if (verification.verified) {
  // 5. Configure webhooks
  await client.webhooks.configure({
    provider: 'sendgrid',
    webhook_url: 'https://myapp.com/webhooks/email'
  });
  
  console.log('✅ Email infrastructure ready!');
}

Browser Support

This package works in Node.js and modern browsers that support:

• Fetch API
• Promises/async-await
• AbortController (for timeouts)

For older browsers, use polyfills for fetch and AbortController.

Requirements

• Node.js >= 14.0.0
• Platform Services API access
• Valid API key and Platform ID

License

MIT © ZyteHub

Support

• Issues: Report bugs at your Platform Services dashboard
• Email: [email protected]
• Documentation: https://docs.yourplatform.com

Related Packages

• @zytehub/email-react - React components for email management UI (coming soon)
• @zytehub/auth-client - Authentication SDK (coming soon)

Made with ❤️ by ZyteHub