Email (SMTP)

DieselEngine provides email sending via SimpleJavaMail. Build emails with a fluent API and send them through any SMTP server.

Quick Example

const email = diesel.getEmailBuilder()
  .from("noreply@example.com")
  .to("user@example.com")
  .withSubject("Welcome!")
  .withHTMLText("<h1>Hello!</h1><p>Welcome to our platform.</p>");

const mailer = diesel.getMailerBuilder("smtp.example.com", 587, "user", "pass");
mailer.buildMailer().sendMail(email.buildEmail());

Building an Email

diesel.getEmailBuilder()

Start building an email message.

• Returns: EmailPopulatingBuilder

Email Builder Methods

Chain these methods to compose the email:

Method	Description
.from(email)	Set the sender address
.from(name, email)	Set the sender with display name
.to(email)	Add a recipient
.to(name, email)	Add a recipient with display name
.cc(email)	Add a CC recipient
.bcc(email)	Add a BCC recipient
.withSubject(subject)	Set the subject line
.withHTMLText(html)	Set the HTML body
.withPlainText(text)	Set the plain-text body
.withReplyTo(email)	Set the reply-to address
.buildEmail()	Build the final Email object

Example: Rich Email

const email = diesel.getEmailBuilder()
  .from("Acme Corp", "noreply@acme.com")
  .to("Alice Smith", "alice@example.com")
  .cc("bob@example.com")
  .withSubject("Your Order #1234 has shipped")
  .withHTMLText(`
    <h1>Order Shipped!</h1>
    <p>Hi Alice,</p>
    <p>Your order <strong>#1234</strong> has been shipped
       and should arrive within 3-5 business days.</p>
    <p>Track your order: <a href="https://example.com/track/1234">here</a></p>
  `)
  .withPlainText("Order #1234 has shipped. Track at: https://example.com/track/1234");

Creating a Mailer

diesel.getMailerBuilder(host, port, username, password)

Create an SMTP mailer with TLS transport strategy.

• Parameters:
  • host: string — SMTP server hostname
  • port: number — SMTP port (typically 587 for TLS, 465 for SSL)
  • username: string — SMTP username
  • password: string — SMTP password
• Returns: MailerRegularBuilderImpl

const mailer = diesel.getMailerBuilder(
  "smtp.example.com",
  587,
  "noreply@example.com",
  "smtp-password"
);

Sending

mailer.buildMailer().sendMail(email.buildEmail());

Common Patterns

Notification Service

// /services/EmailService.js
export class EmailService {

  static sendWelcomeEmail(user) {
    const email = diesel.getEmailBuilder()
      .from("Acme Corp", "noreply@acme.com")
      .to(user.name, user.email)
      .withSubject("Welcome to Acme!")
      .withHTMLText(`<h1>Welcome, ${user.name}!</h1><p>Your account is ready.</p>`)
      .buildEmail();

    EmailService.getMailer().sendMail(email);
  }

  static sendPasswordReset(userEmail, resetLink) {
    const email = diesel.getEmailBuilder()
      .from("Acme Corp", "noreply@acme.com")
      .to(userEmail)
      .withSubject("Reset your password")
      .withHTMLText(`<p>Click <a href="${resetLink}">here</a> to reset your password.</p>`)
      .buildEmail();

    EmailService.getMailer().sendMail(email);
  }

  static getMailer() {
    const host = diesel.getRegistryValue("SMTP_HOST");
    const port = parseInt(diesel.getRegistryValue("SMTP_PORT"));
    const user = diesel.getRegistryValue("SMTP_USER");
    const pass = diesel.getRegistryValue("SMTP_PASS");
    return diesel.getMailerBuilder(host, port, user, pass).buildMailer();
  }
}

Template-Based Emails

function sendTemplatedEmail(to, subject, templatePath, variables) {
  // Use diesel.mergeTemplateToString for template rendering
  const html = diesel.mergeTemplateToString(templatePath, variables);

  const email = diesel.getEmailBuilder()
    .from("noreply@example.com")
    .to(to)
    .withSubject(subject)
    .withHTMLText(html)
    .buildEmail();

  const mailer = diesel.getMailerBuilder("smtp.example.com", 587, "user", "pass");
  mailer.buildMailer().sendMail(email);
}

// Usage
sendTemplatedEmail(
  "alice@example.com",
  "Monthly Report",
  "/tmp/dieselfuse/templates/report-email.html",
  { name: "Alice", month: "March", total: "1,234" }
);

SMTP Credentials from Registry

Store SMTP credentials in the registry instead of hardcoding:

// Set once (e.g., via MCP or startup script)
diesel.setRegistryValue("SMTP_HOST", "smtp.example.com");
diesel.setRegistryValue("SMTP_PORT", "587");
diesel.setRegistryValue("SMTP_USER", "noreply@example.com");
diesel.setRegistryValue("SMTP_PASS", "secret");

// Use from any script
const mailer = diesel.getMailerBuilder(
  diesel.getRegistryValue("SMTP_HOST"),
  parseInt(diesel.getRegistryValue("SMTP_PORT")),
  diesel.getRegistryValue("SMTP_USER"),
  diesel.getRegistryValue("SMTP_PASS")
);