@ircg/tes

Transactional Email Service (TES) SDK for IRCG.

Installation

pnpm add @ircg/tes

Usage

import { TESClient } from '@ircg/tes';

// Initialize the client
const tes = new TESClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://ircg.dev' // optional, defaults to https://ircg.dev
});

// Send a simple text email
await tes.sendText(
  '[email protected]',
  '[email protected]',
  'Hello from IRCG',
  'This is a plain text email.'
);

// Send an HTML email
await tes.sendHtml(
  '[email protected]',
  '[email protected]',
  'Welcome!',
  '<h1>Welcome to our service!</h1><p>Thank you for signing up.</p>',
  'Welcome to our service! Thank you for signing up.' // optional text fallback
);

// Send to multiple recipients
await tes.sendText(
  ['[email protected]', '[email protected]'],
  '[email protected]',
  'Bulk notification',
  'This email is sent to multiple recipients.'
);

// Advanced usage with all options
const result = await tes.send({
  sender: '[email protected]',
  recipients: ['[email protected]'],
  subject: 'Important notification',
  html: '<p>HTML content</p>',
  text: 'Text content',
  carbon_copy: '[email protected]',
  reply_to: '[email protected]'
}, 'complete');

console.log(result.email_sent);

API Reference

TESClient

Constructor

new TESClient(config: IRCGClientConfig)

• config.apiKey (required): Your IRCG API key
• config.baseUrl (optional): Base URL for the API (default: 'https://ircg.dev')

Methods

send(data)

Send a transactional email with full control.

• data.recipients (required): Recipient email address(es)
• data.sender (required): Sender email address
• data.subject (required): Email subject
• data.html (optional): HTML content
• data.text (optional): Plain text content
• data.carbon_copy (optional): CC email address(es)
• data.reply_to (optional): Reply-to email address(es)
• data.fields (required): Array of fields to include in the response
• data.lang (optional): Language for error messages ('es' | 'en')

Note: At least one of html or text must be provided.

Returns: Promise<{ email_sent?, error? }>

sendText(to, from, subject, text, fields)

Send a simple plain text email.

• to (required): Recipient email address
• from (required): Sender email address
• subject (required): Email subject
• text (required): Plain text content
• fields (required): Array of fields to include in the response

Returns: Promise<{ email_sent?, error? }>

sendHtml(to, from, subject, html, text?, fields?)

Send an HTML email with optional text fallback.

• to (required): Recipient email address
• from (required): Sender email address
• subject (required): Email subject
• html (required): HTML content
• text (optional): Plain text fallback
• fields (required): Array of fields to include in the response

Returns: Promise<{ email_sent?, error? }>

Important Notes

Domain Verification

The sender email address must use a domain that is verified in your IRCG account. For example, if you have verified yourdomain.com, you can send from:

• [email protected]
• [email protected]
• Any email at yourdomain.com

Rate Limits

Be aware of your service's rate limits. The SDK will throw an IRCGRateLimitError if you exceed your quota.

Error Handling

import { TESClient } from '@ircg/tes';
import { 
  IRCGError, 
  IRCGAuthenticationError, 
  IRCGValidationError,
  IRCGRateLimitError 
} from '@ircg/core';

const tes = new TESClient({ apiKey: 'your-api-key' });

try {
  await tes.sendText(
    'invalid-email',
    '[email protected]',
    'Test',
    'Test message'
  );
} catch (error) {
  if (error instanceof IRCGAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof IRCGValidationError) {
    console.error('Validation error:', error.details);
  } else if (error instanceof IRCGRateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof IRCGError) {
    console.error('IRCG error:', error.message);
  }
}

License

MIT