funcnode-mail (FnMailer)

Mail sending for Crystal (>= 1.20.2) web services: several mailboxes of one domain, persistent file spool, retries with backoff, rate limiting, bulk campaigns, IMAP bounce monitoring, suppression list, Crystal and HTTP callbacks. Fully thread-safe; works under -Dpreview_mt.

Two deployment modes share one interface (Funcnode::Mail::MailerApi + AdminApi via #admin), so switching is one initialization line:

• Embedded — FnMailer.new(config) inside your application process.
• Remote — the fn-mailer-server binary on a mail host + Client.new(host, port, token: ...) in the application (TCP/MessagePack protocol, optional TLS, token auth); fn-mailer-ctl for operations.

Quick taste

require "funcnode-mail"
alias Mail = Funcnode::Mail

mailer = Mail::FnMailer.new("config/mail.yaml") # missing file -> commented template + ConfigError

send_id = mailer.send(Mail::Message.new(
  from: "no-reply",                        # mailbox key from the config
  to: Mail::Address.new("user@example.com"),
  subject: "Confirm your email",
  text_body: "Follow the link: ...",
  idempotency_key: "confirm:42"))          # repeated send returns the same id

mailer.on_event { |event| ... }            # queued/accepted/failed/bounced/...

Documentation (Russian)

Full documentation with examples lives in doc/:

• Обзор — возможности, режимы, надёжность, доставляемость
• Конфигурация — YAML-файл, шаблон, секреты, sandbox
• Встроенный режим — отправка, кампании, события, admin
• Удалённый режим — сервер, клиент, fn-mailer-ctl, протокол
• Справочник API — MailerApi, AdminApi, типы, ошибки

Runnable programs: examples/.

Installation

dependencies:
  funcnode-mail:
    gitlab: funcnode_crystal/funcnode-mail

Windows note: shards install needs Developer Mode (symlinks).

Development

crystal spec        # also -Dpreview_mt / --no-debug variants
crystal tool format
shards build        # fn-mailer-server, fn-mailer-ctl

Contributors

• Vasily Buter — creator and maintainer