Features
Email Sending
Send transactional and marketing emails with ease
Contact Management
Create, update, and manage contacts
Audience Management
Organize contacts into targeted audiences
Email Templates
Use templates with variable substitution
Attachments
Support for file attachments in various formats
Retry Mechanism
Built-in retry system for improved reliability
Error Handling
Comprehensive error handling and reporting
Installation
TerminalTerminal
1
2
3
4
5
6
7
8
# Using npm
npm install metigan
# Using yarn
yarn add metigan
# Using pnpm
pnpm add metiganQuick Start
quick-start.tsTypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import Metigan from 'metigan';
// Initialize the SDK with your API key
const metigan = new Metigan('your_api_key');
// Send a simple email
async function sendWelcomeEmail() {
try {
const response = await metigan.sendEmail({
from: 'your-company@example.com',
recipients: ['new-user@example.com'],
subject: 'Welcome to Our Service',
content: '<h1>Welcome!</h1><p>Thank you for signing up.</p>',
});
console.log('Email sent successfully:', response);
} catch (error) {
console.error('Failed to send email:', error);
}
}
sendWelcomeEmail();Configuration
The Metigan SDK can be configured with various options:
config.tsTypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const metigan = new Metigan('your_api_key', {
// User ID for logs (optional)
userId: 'your-user-id',
// Disable logs (optional)
disableLogs: false,
// Number of retry attempts for failed operations (optional, default: 3)
retryCount: 5,
// Base time between retry attempts in ms (optional, default: 1000)
retryDelay: 2000,
// Timeout for requests in ms (optional, default: 30000)
timeout: 60000,
});Examples
Basic Email
basic-email.tsTypeScript
1
2
3
4
5
6
await metigan.sendEmail({
from: 'your-company@example.com',
recipients: ['user@example.com', 'another-user@example.com'],
subject: 'Important Update',
content: '<h1>New Features Available</h1><p>Check out our latest updates...</p>',
});Email with Attachments
email-with-attachments.tsTypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Browser environment (using File objects)
const file = new File(['file content'], 'document.pdf', { type: 'application/pdf' });
// Node.js environment
const nodeAttachment = {
buffer: Buffer.from('file content'),
originalname: 'document.pdf',
mimetype: 'application/pdf',
};
// Custom attachment
const customAttachment = {
content: 'file content as string or buffer',
filename: 'document.pdf',
contentType: 'application/pdf',
};
await metigan.sendEmail({
from: 'your-company@example.com',
recipients: ['user@example.com'],
subject: 'Document Attached',
content: '<p>Please find the attached document.</p>',
attachments: [file], // or [nodeAttachment] or [customAttachment]
});Email with Template
email-with-template.tsTypeScript
1
2
3
4
5
6
await metigan.sendEmailWithTemplate({
from: 'your-company@example.com',
recipients: ['user@example.com'],
subject: 'Welcome to Our Service',
templateId: 'welcome-template-id',
});Error Handling
The Metigan SDK provides comprehensive error handling with specific error types:
error-handling.tsTypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import { MetiganError, ValidationError, ApiError, NetworkError, ContactError } from 'metigan';
import { ErrorCode } from 'metigan';
try {
await metigan.sendEmail({
// Email options
});
} catch (error) {
if (error instanceof MetiganError) {
console.error(`Error code: ${error.code}, Message: ${error.message}`);
// Handle specific error types
if (error instanceof ValidationError) {
console.error('Validation failed');
} else if (error instanceof ApiError) {
console.error(`API error with status: ${error.status}`);
} else if (error instanceof NetworkError) {
console.error('Network connectivity issue');
} else if (error instanceof ContactError) {
console.error('Contact operation failed');
}
// Handle specific error codes
switch (error.code) {
case ErrorCode.INVALID_API_KEY:
console.error('Invalid API key. Please check your credentials.');
break;
case ErrorCode.MISSING_REQUIRED_FIELD:
console.error('Missing required field in request.');
break;
case ErrorCode.INVALID_EMAIL_FORMAT:
console.error('Invalid email format.');
break;
// Handle other error codes
}
} else {
console.error('Unknown error:', error);
}
}API Reference
Core Methods
| Method | Description |
|---|---|
| sendEmail(options) | Sends an email with the specified options |
| sendEmailWithTemplate(options) | Sends an email using a template |
| generateTrackingId() | Generates a unique tracking ID for email analytics |
Contact Methods
| Method | Description |
|---|---|
| createContacts(emails, options) | Creates contacts in the specified audience |
| getContact(email, audienceId) | Gets a contact by email |
| listContacts(options) | Lists contacts in an audience |
| updateContact(email, options) | Updates a contact |
| deleteContact(contactId, audienceId) | Deletes a contact |
Audience Methods
| Method | Description |
|---|---|
| createAudience(options) | Creates a new audience |
| getAudiences() | Gets all audiences |
| getAudience(id) | Gets an audience by ID |
| updateAudience(id, options) | Updates an audience |
| deleteAudience(id) | Deletes an audience |
Combined Methods
| Method | Description |
|---|---|
| sendEmailAndCreateContacts(options) | Sends an email and creates contacts in one operation |
| sendTemplateAndCreateContacts(options) | Sends a template email and creates contacts in one operation |
TypeScript Support
The Metigan SDK is written in TypeScript and provides comprehensive type definitions for all methods and options.
types.tsTypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import type {
EmailOptions,
EmailSuccessResponse,
EmailErrorResponse,
ApiKeyErrorResponse,
EmailApiResponse,
ContactApiResponse,
ContactCreationOptions,
ContactQueryOptions,
ContactUpdateOptions,
ContactData,
NodeAttachment,
CustomAttachment,
TemplateVariables,
TemplateFunction,
TemplateOptions,
TemplateApiResponse,
AudienceApiResponse,
AudienceCreationOptions,
AudienceUpdateOptions,
} from 'metigan';