Shoutbox.net is a Developer API designed to send transactional emails at scale. This documentation covers all integration methods, from direct API calls to framework integration.
There are four main ways to integrate with Shoutbox:
- Direct API calls using fetch()
- Using our Node.js client
- Using SMTP
- Next.js integration
- React Email Components
If you want to make direct API calls without any dependencies:
const apiKey = 'your-api-key-here';
const emailData = {
from: '[email protected]',
to: '[email protected]',
subject: 'Test Email',
html: '<h1>Hello!</h1><p>This is a test email.</p>',
name: 'Sender Name',
replyTo: '[email protected]'
};
async function sendEmail() {
try {
const response = await fetch('https://api.shoutbox.net/send', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(emailData)
});
if (response.ok) {
console.log('Email sent successfully!');
} else {
console.error('Failed to send email:', await response.text());
}
} catch (error) {
console.error('Error sending email:', error);
}
}
sendEmail();npm install shoutboxnetimport Shoutbox from "shoutboxnet";
const client = new Shoutbox('your-api-key');
async function sendEmail() {
await client.sendEmail({
from: '[email protected]',
to: '[email protected]',
subject: 'Test Email',
html: '<h1>Hello!</h1><p>This is a test email.</p>',
name: 'Sender Name',
replyTo: '[email protected]'
});
}
sendEmail();For SMTP integration, use our SMTPClient:
import { SMTPClient } from "shoutboxnet";
const smtp = new SMTPClient('your-api-key');
async function sendEmailViaSMTP() {
// Verify connection first
const isConnected = await smtp.verifyConnection();
if (!isConnected) {
console.error('Failed to connect to SMTP server');
return;
}
// Send email
await smtp.sendEmail({
from: '[email protected]',
to: '[email protected]',
subject: 'SMTP Test',
html: '<h1>Hello!</h1><p>This is a test email via SMTP.</p>',
name: 'Sender Name',
replyTo: '[email protected]'
});
}
sendEmailViaSMTP();npm install shoutboxnet- Create an API route in
pages/api/send-email.ts:
import type { NextApiRequest, NextApiResponse } from 'next';
import Shoutbox from 'shoutboxnet';
// Initialize client outside handler to reuse connection
const client = new Shoutbox(process.env.SHOUTBOX_API_KEY!);
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
if (req.method !== 'POST') {
return res.status(405).json({ message: 'Method not allowed' });
}
try {
const { from, to, subject, html } = req.body;
await client.sendEmail({
from,
to,
subject,
html
});
res.status(200).json({ message: 'Email sent successfully' });
} catch (error) {
console.error('Error sending email:', error);
res.status(500).json({ message: 'Failed to send email' });
}
}- Add your API key to
.env.local:
SHOUTBOX_API_KEY=your-api-key-here- Use in your components:
'use client';
import { useState } from 'react';
export default function ContactForm() {
const [status, setStatus] = useState('');
async function handleSubmit(e: React.FormEvent) {
e.preventDefault();
setStatus('Sending...');
try {
const res = await fetch('/api/send-email', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
from: '[email protected]',
to: '[email protected]',
subject: 'New Contact Form Submission',
html: '<h1>New Contact</h1><p>You have a new contact form submission.</p>'
}),
});
if (res.ok) {
setStatus('Email sent successfully!');
} else {
setStatus('Failed to send email');
}
} catch (error) {
setStatus('Error sending email');
console.error('Error:', error);
}
}
return (
<form onSubmit={handleSubmit}>
<button type="submit">Send Email</button>
{status && <p>{status}</p>}
</form>
);
}If you're using Server Actions in Next.js 14 or later, you can send emails directly from your server components:
// app/actions.ts
'use server';
import Shoutbox from 'shoutboxnet';
const client = new Shoutbox(process.env.SHOUTBOX_API_KEY!);
export async function sendEmail(formData: FormData) {
try {
await client.sendEmail({
from: '[email protected]',
to: formData.get('email') as string,
subject: 'New Contact Form Submission',
html: '<h1>New Contact</h1><p>You have a new contact form submission.</p>'
});
return { success: true };
} catch (error) {
console.error('Error sending email:', error);
return { success: false, error: 'Failed to send email' };
}
}
// app/page.tsx
import { sendEmail } from './actions';
export default function ContactPage() {
return (
<form action={sendEmail}>
<input type="email" name="email" required />
<button type="submit">Send Email</button>
</form>
);
}Shoutbox supports sending emails using React components through integration with @react-email. This allows you to create dynamic, reusable email templates using React's component-based architecture.
npm install shoutboxnet @react-email/componentsimport React from 'react';
import Shoutbox from 'shoutboxnet';
import { Html } from '@react-email/html';
import { Button } from '@react-email/button';
import { Text } from '@react-email/text';
import { Section } from '@react-email/section';
import { Container } from '@react-email/container';
interface WelcomeEmailProps {
url: string;
name: string;
}
function WelcomeEmail({ url, name }: WelcomeEmailProps) {
return (
<Html>
<Section style={{ backgroundColor: '#ffffff' }}>
<Container>
<Text>Hello {name}!</Text>
<Text>Welcome to our platform. Please verify your email:</Text>
<Button href={url}>Verify Email</Button>
</Container>
</Section>
</Html>
);
}
const client = new Shoutbox('your-api-key');
await client.sendEmail({
from: "[email protected]",
to: "[email protected]",
subject: "Welcome to Our Platform",
react: <WelcomeEmail url="https://example.com/verify" name="John" />
});Shoutbox supports all @react-email components including:
<Html>: Root component for email templates<Button>: Styled button component<Text>: Text component with email-safe styling<Section>: Section container for layout<Container>: Centered container with max-width- And many more from the @react-email library
React components can include dynamic content through props, conditional rendering, and loops:
interface EmailProps {
user: {
name: string;
items: string[];
};
}
function OrderConfirmation({ user }: EmailProps) {
return (
<Html>
<Section>
<Text>Thank you for your order, {user.name}!</Text>
{user.items.map((item, index) => (
<Text key={index}>- {item}</Text>
))}
</Section>
</Html>
);
}Required environment variables:
SHOUTBOX_API_KEY=your-api-key-hereFor development and testing, see our development guide.
This library is licensed under the MIT License. See the LICENSE file for details.