CandyMail
Email sending — SMTP + Resend HTTP API transports, attachments
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
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by charmbracelet/pop (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| static new(from, to, ?subject, ?body) | Create an email | |
| withFrom() / withTo(...$to) / withCc(...) / withBcc(...) / withReplyTo() / withSubject() | Immutable header builders | |
| withBody() / withHtmlBody() / withSignature() | Plain-text and HTML bodies | |
| withAttachment(filename, path) / withInlineAttachment(path, cid, ?filename) | Attach a file, or embed one for a cid: reference | |
| bodyWithSignature() / allRecipients() | Body with signature applied; combined to/cc/bcc list | |
| Transport | send(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 |
| MissingTransportConfig | extends RuntimeException — catch by type, never by message text | The 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 |
| SmtpTransport | withRequireTls() / withImplicitTls() / withCaFile(caFile) | TLS policy and custom CA trust anchor |
| SmtpTransport | buildMimeMessage(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 |
| Attachment | static fromPath(path, ?filename) / static inline(path, cid, ?filename) | Attachment value objects |
| Attachment | static 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.