Language & Framework guides
Next.js - Typescript - Javascript - Python - PHP - Laravel - Go
Shoutbox.net is a Developer API designed to send transactional emails at scale. This documentation covers all integration methods, from direct API calls to full framework integration.
For these integrations to work, you will need an account on Shoutbox.net. You can create and copy the required API key on the Shoutbox.net dashboard!
The API key is required for any call to the Shoutbox.net backend; for SMTP, the API key is your password and 'shoutbox' the user to send emails.
There are three main ways to integrate with Shoutbox:
- Direct API calls (no dependencies)
- Using our PHP library with Composer
- Laravel framework integration
If you want to avoid dependencies, you can make direct API calls:
<?php
// Your API key from Shoutbox.net
$apiKey = 'your-api-key-here';
// Prepare email data
$data = [
'from' => '[email protected]',
'to' => '[email protected]',
'subject' => 'Test Email',
'html' => '<h1>Hello!</h1><p>This is a test email.</p>',
'name' => 'Sender Name',
'reply_to' => '[email protected]'
];
// Make the API call
$ch = curl_init('https://api.shoutbox.net/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
// Handle the response
if ($httpCode >= 200 && $httpCode < 300) {
echo "Email sent successfully!\n";
} else {
echo "Failed to send email. Status code: $httpCode\n";
}- No dependencies required
- Simple cURL implementation
- Full control over the request
- Lightweight integration
- Suitable for simple implementations
composer require shoutboxnet/shoutboxThe API client provides an object-oriented interface to the REST API:
<?php
require 'vendor/autoload.php';
use Shoutbox\Client;
use Shoutbox\EmailOptions;
use Shoutbox\Attachment;
// Initialize client
$apiKey = getenv('SHOUTBOX_API_KEY') ?: 'your-api-key-here';
$client = new Client($apiKey);
try {
// Basic email
$options = new EmailOptions();
$options->from = '[email protected]';
$options->to = '[email protected]';
$options->subject = 'Test Email';
$options->html = '<h1>Hello!</h1><p>This is a test email.</p>';
$options->name = 'Sender Name';
$options->replyTo = '[email protected]';
$client->sendEmail($options);
// Email with attachment
$attachment = new Attachment();
$attachment->filepath = './document.pdf';
$attachment->filename = 'document.pdf';
$attachment->contentType = 'application/pdf';
$optionsWithAttachment = new EmailOptions();
$optionsWithAttachment->from = '[email protected]';
$optionsWithAttachment->to = '[email protected]';
$optionsWithAttachment->subject = 'Test Email with Attachment';
$optionsWithAttachment->html = '<h1>Hello!</h1><p>This email includes an attachment.</p>';
$optionsWithAttachment->attachments = [$attachment];
$client->sendEmail($optionsWithAttachment);
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}The SMTP client provides an alternative way to send emails:
<?php
require 'vendor/autoload.php';
use Shoutbox\SMTPClient;
use Shoutbox\EmailOptions;
$client = new SMTPClient('your-api-key-here');
try {
// Multiple recipients
$options = new EmailOptions();
$options->from = '[email protected]';
$options->to = ['[email protected]', '[email protected]'];
$options->subject = 'Test Email';
$options->html = '<h1>Hello!</h1><p>This is a test email.</p>';
$options->headers = [
'X-Custom-Header' => 'Custom Value',
'X-Priority' => '1'
];
$client->sendEmail($options);
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}- Type-safe email options
- Built-in error handling
- File attachment support
- Custom headers support
- Multiple recipient types (to, cc, bcc)
- Choice between API and SMTP clients
- Install the package:
composer require shoutboxnet/shoutbox- Add configuration to
config/services.php:
'shoutbox' => [
'key' => env('SHOUTBOX_API_KEY'),
],- Add to
.env:
SHOUTBOX_API_KEY=your-api-key-here
use Illuminate\Support\Facades\Mail;
Mail::to('[email protected]')
->send(new ShoutboxMail('<h1>Hello</h1><p>This is a test email.</p>'));Mail::to('[email protected]')
->from('[email protected]', 'Sender Name')
->replyTo('[email protected]')
->cc(['[email protected]', '[email protected]'])
->send(new ShoutboxMail('<h1>Hello</h1><p>This is a test email.</p>'));class SendEmailJob implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function handle()
{
Mail::to('[email protected]')
->send(new ShoutboxMail('<h1>Hello</h1><p>This is a queued email.</p>'));
}
}- Full Laravel Mail integration
- Queue support
- Rate limiting
- Exception handling
- Configuration management
- Service provider auto-discovery
The EmailOptions class supports:
- from (string): Sender's email address
- to (string|string[]): Recipient email address(es)
- subject (string): Email subject
- html (string): HTML content
- text (string): Plain text content
- name (string): Sender's name
- replyTo (string): Reply-to address
- cc (string|string[]): CC recipients
- bcc (string|string[]): BCC recipients
- attachments (Attachment[]): File attachments
- headers (array): Custom headers
- tags (array): Email tags
- filepath: Path to the file
- filename: Name for the attachment (optional)
- contentType: MIME type (optional)
- content: Base64 encoded content (optional)
- API Client is recommended for most use cases
- SMTP Client is useful for legacy system compatibility
- Both support the same features
- Store API keys securely
- Use environment variables
- Validate email addresses
- Sanitize HTML content
- Use queues for bulk sending
- Implement rate limiting
- Handle errors gracefully
- Monitor API responses
- Use test API keys
- Mock API calls in tests
- Verify email delivery
- Check spam scores
- Clone the repository:
git clone https://github.com/shoutboxnet/shoutbox-PHP.git- Install dependencies:
composer install- Run tests:
composer test- GitHub Issues for bug reports
- Email support for critical issues
- Documentation for guides and examples
- Regular updates and maintenance
This library is licensed under the MIT License. See the LICENSE file for details.