​
TypeScript SMTP Integration

Our TypeScript SMTP client provides direct mail server integration with full type safety.

​
Installation

npm install shoutboxnet
# or
yarn add shoutboxnet
# or
pnpm add shoutboxnet

​
Using the SMTP Client

​
Basic Usage

import { SMTPClient } from 'shoutboxnet';
import { EmailOptions } from 'shoutboxnet';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

// Verify connection
const isConnected = await smtp.verifyConnection();
if (!isConnected) {
    throw new Error('Failed to connect to SMTP server');
}

const emailOptions: EmailOptions = {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hello from SMTP!',
    html: '<h1>Hello!</h1><p>This is a test email via SMTP.</p>'
};

try {
    await smtp.sendEmail(emailOptions);
    console.log('Email sent successfully');
} catch (error) {
    console.error('Failed to send email:', error);
}

​
With Multiple Recipients

import { SMTPClient, EmailOptions } from 'shoutboxnet';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

const emailOptions: EmailOptions = {
    from: '[email protected]',
    to: ['[email protected]', '[email protected]'],
    subject: 'Group Announcement',
    html: '<h1>Hello Team!</h1><p>This is a group announcement.</p>'
};

await smtp.sendEmail(emailOptions);

​
With Attachments

import { SMTPClient, EmailOptions, Attachment } from 'shoutboxnet';
import { readFileSync } from 'fs';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

const attachment: Attachment = {
    filepath: './document.pdf',
    filename: 'report.pdf',
    contentType: 'application/pdf'
};

const emailOptions: EmailOptions = {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Report Attached',
    html: '<h1>Monthly Report</h1><p>Please find the report attached.</p>',
    attachments: [attachment]
};

await smtp.sendEmail(emailOptions);

​
With Custom Headers

import { SMTPClient, EmailOptions } from 'shoutboxnet';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

const emailOptions: EmailOptions = {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Custom Headers Example',
    html: '<h1>Hello!</h1>',
    headers: {
        'X-Custom-Header': 'custom-value',
        'X-Campaign-ID': 'campaign-123'
    }
};

await smtp.sendEmail(emailOptions);

​
With CC Recipients

import { SMTPClient, EmailOptions } from 'shoutboxnet';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

const emailOptions: EmailOptions = {
    from: '[email protected]',
    to: '[email protected]',
    cc: ['[email protected]', '[email protected]'],
    subject: 'CC Example',
    html: '<h1>Hello!</h1><p>This email has CC recipients.</p>'
};

await smtp.sendEmail(emailOptions);

​
Sending Multiple Emails

import { SMTPClient, EmailOptions } from 'shoutboxnet';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

const emails: EmailOptions[] = [
    {
        from: '[email protected]',
        to: '[email protected]',
        subject: 'Email 1',
        html: '<h1>First Email</h1>'
    },
    {
        from: '[email protected]',
        to: '[email protected]',
        subject: 'Email 2',
        html: '<h1>Second Email</h1>'
    }
];

await smtp.sendEmails(emails);

​
Error Handling

import { SMTPClient, EmailOptions } from 'shoutboxnet';

const smtp = new SMTPClient(process.env.SHOUTBOX_API_KEY);

async function sendEmailWithRetry(options: EmailOptions, maxRetries: number = 3): Promise<void> {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            // Verify connection before sending
            const isConnected = await smtp.verifyConnection();
            if (!isConnected) {
                throw new Error('Failed to connect to SMTP server');
            }

            await smtp.sendEmail(options);
            return;
        } catch (error) {
            if (attempt === maxRetries) {
                throw error;
            }
            console.log(`Attempt ${attempt} failed, retrying...`);
            await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        }
    }
}

// Usage
try {
    await sendEmailWithRetry({
        from: '[email protected]',
        to: '[email protected]',
        subject: 'Test with Retry',
        html: '<h1>Hello!</h1>'
    });
} catch (error) {
    console.error('All retry attempts failed:', error);
}

​
Type Definitions

​
EmailOptions Interface

interface EmailOptions {
    from: string;
    to: string | string[];
    subject: string;
    html?: string;
    text?: string;
    react?: React.ReactElement;
    name?: string;
    replyTo?: string;
    attachments?: Attachment[];
    headers?: Record<string, string>;
    cc?: string | string[];
}

​
Attachment Interface

interface Attachment {
    filename?: string;
    filepath: string;
    contentType?: string;
    content?: string | Buffer;
}

​
Environment Variables

// .env
SHOUTBOX_API_KEY=your-api-key-here

// Usage
import { config } from 'dotenv';
import { SMTPClient } from 'shoutboxnet';

config();

const apiKey = process.env.SHOUTBOX_API_KEY;
if (!apiKey) {
    throw new Error('SHOUTBOX_API_KEY is required');
}

const smtp = new SMTPClient(apiKey);

​
Rate Limits

Please contact support for information about rate limits for your API key.

​
Support

For additional support or questions, please contact our support team.