Mailer And SMTP

Geblang includes two layers for email:

• mailer: source-level classes for application code.
• smtp: low-level native functions for MIME rendering and SMTP delivery.

Most applications should import mailer. It gives you typed message, attachment, transport, and sender objects while still producing plain MIME and using SMTP underneath.

Quick Start

import mailer;

let message = mailer.Message("Welcome")
    .fromAddress("App <noreply@example.com>")
    .toAddress("Ada <ada@example.com>")
    .withText("Hello Ada,\n\nYour account is ready.")
    .withHtml("<h1>Hello Ada</h1><p>Your account is ready.</p>");

let transport = mailer.smtpTransport("smtp.example.com", 587, "user", "secret")
    .fromAddress("App <noreply@example.com>");

let client = mailer.Mailer(transport);
client.send(message);

fromAddress may be set on the message or the transport. The message-level sender wins; the transport sender is useful when most mail from an application uses the same address.

Messages

mailer.Message(subject) starts an email message. It supports fluent mutation:

let message = mailer.Message("Invoice")
    .fromAddress("Billing <billing@example.com>")
    .toAddress("customer@example.com")
    .ccAddress("accounts@example.com")
    .bccAddress("audit@example.com")
    .withReplyTo("support@example.com")
    .withHeader("X-Customer-Id", "cust_123")
    .withText("Your invoice is attached.")
    .withHtml("<p>Your invoice is attached.</p>");

Methods:

When both text and HTML are present, Geblang renders a multipart/alternative body. When attachments are present, the message becomes multipart/mixed with the text/HTML body as the first part.

Attachments

Use mailer.Attachment(filename, content) for in-memory content. content may be a string or bytes.

import bytes;
import mailer;

let report = mailer.Attachment("report.txt", "daily summary")
    .withContentType("text/plain");

let image = mailer.Attachment("logo.png", bytes.fromBase64("..."))
    .withContentType("image/png")
    .asInline("logo");

Use attachmentFromPath(path, contentType) when the content should be read from disk as the message is rendered or sent:

let pdf = mailer.attachmentFromPath("build/invoice.pdf", "application/pdf");
message.attach(pdf);

Inline attachments set Content-Disposition: inline and a Content-ID header. Reference them from HTML with cid:<id>:

let message = mailer.Message("Logo")
    .withHtml("<img src=\"cid:logo\">")
    .attach(mailer.Attachment("logo.png", imageBytes).withContentType("image/png").asInline("logo"));

SMTP Transport

mailer.SmtpTransport(host, port, username, password) configures SMTP.

let transport = mailer.SmtpTransport("smtp.example.com", 587, "user", "secret")
    .fromAddress("App <noreply@example.com>")
    .withStartTLS(true)
    .withTLS(false)
    .withHello("app.example.com");

Transport methods:

Low-Level smtp

The native smtp module accepts dictionaries. This is useful for framework code, tests, or adapter modules.

import smtp;

let message = {
    "from": "App <noreply@example.com>",
    "to": ["Ada <ada@example.com>"],
    "subject": "Welcome",
    "text": "Hello Ada",
    "html": "<p>Hello Ada</p>",
    "attachments": [
        {
            "filename": "welcome.txt",
            "contentType": "text/plain",
            "content": "Thanks for trying Geblang."
        }
    ]
};

let raw = smtp.message(message);

smtp.send(config, message) sends through an SMTP server and returns a dict:

let result = smtp.send({
    "host": "smtp.example.com",
    "port": 587,
    "username": "user",
    "password": "secret",
    "from": "App <noreply@example.com>",
    "startTLS": true
}, message);

io.println(result["ok"]);
io.println(result["recipients"]);

Message dictionary keys:

Attachment dictionary keys:

Config dictionary keys:

Testing Mail

For tests and previews, render instead of sending:

let raw = client.render(message);
assert(raw.contains("multipart/alternative"));
assert(raw.contains("Subject: Welcome"));

This avoids network access and makes assertions deterministic. A later application framework can wrap mailer.Mailer behind an interface and provide an in-memory test transport.