JavaScript Client Library

Our JavaScript client library provides a simple interface for sending emails through Shoutbox.net.

Installation

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

Using the Client Library

Basic Usage

import Shoutbox from 'shoutboxnet';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

const emailOptions = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Hello from JavaScript!',
    html: '<h1>Hello!</h1><p>This is a test email.</p>'
};

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

With Multiple Recipients

import Shoutbox from 'shoutboxnet';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

const emailOptions = {
    from: 'sender@example.com',
    to: ['recipient1@example.com', 'recipient2@example.com'],
    subject: 'Group Announcement',
    html: '<h1>Hello Team!</h1><p>This is a group announcement.</p>'
};

await client.sendEmail(emailOptions);

With Attachments

import Shoutbox from 'shoutboxnet';
import { readFileSync } from 'fs';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

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

const emailOptions = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Report Attached',
    html: '<h1>Monthly Report</h1><p>Please find the report attached.</p>',
    attachments: [attachment]
};

await client.sendEmail(emailOptions);

With Custom Headers

import Shoutbox from 'shoutboxnet';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

const emailOptions = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Custom Headers Example',
    html: '<h1>Hello!</h1>',
    headers: {
        'X-Custom-Header': 'custom-value',
        'X-Campaign-ID': 'campaign-123'
    }
};

await client.sendEmail(emailOptions);

With CC Recipients

import Shoutbox from 'shoutboxnet';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

const emailOptions = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    cc: ['cc1@example.com', 'cc2@example.com'],
    subject: 'CC Example',
    html: '<h1>Hello!</h1><p>This email has CC recipients.</p>'
};

await client.sendEmail(emailOptions);

Sending Multiple Emails

import Shoutbox from 'shoutboxnet';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

const emails = [
    {
        from: 'sender@example.com',
        to: 'recipient1@example.com',
        subject: 'Email 1',
        html: '<h1>First Email</h1>'
    },
    {
        from: 'sender@example.com',
        to: 'recipient2@example.com',
        subject: 'Email 2',
        html: '<h1>Second Email</h1>'
    }
];

await client.sendEmails(emails);

With React Email Templates

import Shoutbox from 'shoutboxnet';
import { WelcomeTemplate } from './emails/WelcomeTemplate';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

const emailOptions = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome!',
    react: <WelcomeTemplate name="John" />
};

await client.sendEmail(emailOptions);

Error Handling

import Shoutbox from 'shoutboxnet';

const client = new Shoutbox(process.env.SHOUTBOX_API_KEY);

async function sendEmailWithRetry(options, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            await client.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: 'sender@example.com',
        to: 'recipient@example.com',
        subject: 'Test with Retry',
        html: '<h1>Hello!</h1>'
    });
} catch (error) {
    console.error('All retry attempts failed:', error);
}

Request Structure

Email Options

The email options object can include:

• from (required): Sender email address
• to (required): Recipient email address(es)
• subject (required): Email subject line
• html (optional): HTML content of the email
• text (optional): Plain text content
• react (optional): React Email component
• name (optional): Sender name
• replyTo (optional): Reply-to email address
• attachments (optional): Array of attachment objects
• headers (optional): Custom email headers
• cc (optional): CC recipients

Attachment Structure

Attachment objects can include:

• filename: Name of the file
• filepath: Path to the file
• contentType: MIME type of the file
• content: Base64 encoded content or Buffer

Environment Variables

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

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

config();

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

const client = new Shoutbox(apiKey);

Browser Usage

When using in the browser, it’s recommended to use a server-side proxy:

// frontend.js
const client = {
    async sendEmail(options) {
        const response = await fetch('/api/send-email', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(options)
        });

        if (!response.ok) {
            throw new Error('Failed to send email');
        }

        return response.json();
    }
};

// Usage
await client.sendEmail({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Hello!',
    html: '<h1>Hello from the browser!</h1>'
});

Rate Limits

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

Next Steps

• SMTP Integration

Support

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