Send emails with PHP

In this quickstart, you'll learn how to send transactional emails from your PHP project with Sidemail. You'll set up the SDK, send your first email, and see examples for common use cases like welcome emails, password resets, and scheduled reports.

Before you start

1. Create a Sidemail account → get your API key
2. Add a sending domain → set up your domain for sending

1. Install

composer require sidemail/sidemail

2. Setup

Initialize the client. The SDK automatically reads SIDEMAIL_API_KEY from your environment variables.

Option A: Simple setup

Use this for simple scripts.

require_once __DIR__ . '/vendor/autoload.php';

use Sidemail\Sidemail;

$sidemail = new Sidemail();
// or manual: new Sidemail(apiKey: '...');

Option B: Shared instance (Singleton)

For larger applications, create a sidemail.php file that returns a singleton instance.

// create file -> sidemail.php

require_once __DIR__ . '/vendor/autoload.php';

use Sidemail\Sidemail;

// Define a helper function to hold the static instance
if (!function_exists('sidemail_instance')) {
    function sidemail_instance() {
        static $instance;
        if (!$instance) {
            $instance = new Sidemail();
        }
        return $instance;
    }
}

return sidemail_instance();

Usage:

$sidemail = require __DIR__ . '/sidemail.php';

$sidemail->sendEmail([/* ... */]);

3. Send a welcome email

$sidemail->sendEmail([
    'toAddress'     => $email,
    'fromAddress'   => '[email protected]',
    'fromName'      => 'Your App',
    'templateName'  => 'Welcome',
    'templateProps' => ['firstName' => $name],
]);

4. Send a password reset email

Handle form submissions in your script.

$email = $_POST['email'];
$sidemail->sendEmail([
    'toAddress'     => $email,
    'fromAddress'   => '[email protected]',
    'fromName'      => 'Your App',
    'templateName'  => 'Password Reset',
    'templateProps' => [
        'actionUrl' => 'https://myapp.com/reset/token123',
    ],
]);

5. Send a weekly report (Cron Task)

Create a standalone script to run via cron.

// scripts/send-weekly-report.php
// In a real app, fetch this from your database
$newSignups = 150;
$chartData = [100, 200, 300, 400, 200, 300, 200, 500];

$sidemail->sendEmail([
    'toAddress'     => '[email protected]',
    'fromAddress'   => '[email protected]',
    'fromName'      => 'My App',
    'templateName'  => 'Weekly Report',
    'templateProps' => [
        'signups' => $newSignups,
        'chart'   => $chartData,
    ],
]);

Run it via cron:

# Run every Monday at 8:00 AM
0 8 * * 1 php /path/to/scripts/send-weekly-report.php

6. Send HTML email (with PHP template)

Use output buffering (ob_start) to render HTML from a PHP file.

// templates/invoice.php

ob_start();
$amount = 99;
include __DIR__ . '/templates/invoice.php';
$html = ob_get_clean();

$sidemail->sendEmail([
    'toAddress'   => '[email protected]',
    'fromAddress' => '[email protected]',
    'fromName'    => 'Your App',
    'subject'     => 'Your Invoice',
    'html'        => $html,
]);

7. Send Markdown email

Store your markdown content in a file and load it (learn more).

$markdown = file_get_contents(__DIR__ . '/templates/emails/welcome.md');

// Subject and sender are defined in the markdown frontmatter
$sidemail->sendEmail([
    'toAddress'     => '[email protected]',
    'markdown'      => $markdown,
    'templateProps' => [
        'name' => 'John',
        'link' => 'https://example.com',
    ],
]);

8. Send plain text email

$sidemail->sendEmail([
    'toAddress'   => '[email protected]',
    'fromAddress' => '[email protected]',
    'fromName'    => 'Your App',
    'subject'     => 'Hello',
    'text'        => 'Hello! 👋',
]);

9. Schedule email

Send email later. Set scheduledAt to an ISO date string.

$sidemail->sendEmail([
    'toAddress'     => '[email protected]',
    'fromAddress'   => '[email protected]',
    'fromName'      => 'Your App',
    'templateName'  => 'Welcome',
    'templateProps' => ['firstName' => 'Alex'],
    'scheduledAt'   => (new DateTime('+1 hour'))->format(DateTime::ATOM),
]);

10. Send with attachment

Use the Sidemail::fileToAttachment helper to attach files.

$pdfData = file_get_contents(__DIR__ . '/invoice.pdf');
$attachment = Sidemail::fileToAttachment('invoice.pdf', $pdfData);

$sidemail->sendEmail([
    'toAddress'   => '[email protected]',
    'fromAddress' => '[email protected]',
    'fromName'    => 'Your App',
    'subject'     => 'Your invoice',
    'text'        => 'See attached.',
    'attachments' => [$attachment],
]);

11. Handle errors

use Sidemail\SidemailException;

try {
    $sidemail->sendEmail([/* ... */]);
} catch (SidemailException $e) {
    // Log error to file or monitoring system
    error_log('Sidemail error: ' . $e->getMessage());
}