All 22 apps

CandyMail

Email sending — SMTP + Resend HTTP API transports, attachments

inspired by charmbracelet/pop emailmailsmtpattachmentresendmailersend

CandyMail code coverage

Email builder and sender. SMTP transport, Resend API transport, attachment support, HTML + plain-text multipart, and a fluent interface.

Install

composer require sugarcraft/candy-mail

Quickstart

use SugarCraft\Mail\{Email, ResendTransport, SmtpTransport};

// Immutable: every with*() returns a new Email
// The fields double as named arguments — new Email(from: ..., to: ..., subject: ..., body: ...) —
// a partial build stays readable without counting positional slots
$email = Email::new('noreply@example.com', 'user@example.com', 'Deployment complete', 'Your app was deployed successfully.')
    ->withHtmlBody('<p>Your app was deployed <strong>successfully</strong>.</p>')
    ->withCc('ops@example.com')
    ->withAttachment('build.zip', '/tmp/build.zip');   // display name, then the file on disk

// Credentials come from the environment — never from committed source.
$transport = new SmtpTransport(
    host:     'smtp.example.com',
    port:     587,
    username: (string) getenv('CANDY_MAIL_SMTP_USERNAME'),
    password: (string) getenv('CANDY_MAIL_SMTP_PASSWORD'),
);
$transport->send($email);

// Or over the Resend HTTP API (key from the argument or RESEND_API_KEY)
(new ResendTransport())->send($email);

TLS is required by default on the SMTP transport — credentials never travel over a plaintext channel. Keep real passwords and API keys in the environment (the candy-mail CLI reads the same CANDY_MAIL_SMTP_* names); see the TLS & security section of the README.

Attachment paths are read eagerly at build time — the file on disk must exist when withAttachment() is called, or the builder throws a RuntimeException.

What's in the box

SMTP transportTCP connection with TLS, auth (LOGIN via TLS, fail-closed).
Resend transportAPI-based sending via Resend.com — no SMTP needed.
AttachmentsLocal files, memory content, custom MIME types.
HTML + TextMultipart/alternative email bodies.
Command-line senderBody from stdin, repeatable address and attachment flags, offline --render preview.

Source & demos

Try the quickstart →

API

ClassMethodDescription
Emailstatic new(from, to, ?subject, ?body)Create an email
EmailwithFrom() / withTo(...$to) / withCc(...) / withBcc(...) / withReplyTo() / withSubject()Immutable header builders
EmailwithBody() / withHtmlBody() / withSignature()Plain-text and HTML bodies
EmailwithAttachment(filename, path) / withInlineAttachment(path, cid, ?filename)Attach a file, or embed one for a cid: reference
EmailbodyWithSignature() / allRecipients()Body with signature applied; combined to/cc/bcc list
Transportsend(Email, ?token = null)Delivery interface — implement to add a custom transport
Mailer__construct(Transport) / send(Email, ?token = null)Transport-agnostic sender; validates the envelope before dialing
MissingTransportConfigextends RuntimeException — catch by type, never by message textThe typed "no transport is configured" refusal; the CLI --render fallback catches exactly this so a broken config stays a loud error
SmtpTransport__construct(host, port = 587, username = '', password = '', timeout = 30, heloHost = '') / send(Email, ?token = null)SMTP delivery
SmtpTransportwithRequireTls() / withImplicitTls() / withCaFile(caFile)TLS policy and custom CA trust anchor
SmtpTransportbuildMimeMessage(Email, allow8Bit = true)Render the full MIME message without sending
ResendTransport__construct(apiKey = '') / send(Email, ?token = null)Resend API delivery; falls back to RESEND_API_KEY
Attachmentstatic fromPath(path, ?filename) / static inline(path, cid, ?filename)Attachment value objects
Attachmentstatic fromContent(content, filename, mimeType = 'application/octet-stream')Build an attachment from in-memory bytes

Demos.

VHS-recorded GIF of the API showcase, regenerated automatically on every push that touches the source.

Showcase

Showcase

Building Email value objects — transports, recipients, multipart bodies, attachments — and printing their resolved fields, structure visible without any SMTP access.