mailsmtp

📬 Boring SMTP server for Ruby.

Answers one question: how do I receive emails in Ruby?

mailsmtp implements the SMTP protocol so you can plug in your own logic. Receive email in your own app — no Postfix, no ESP required. As the conversation progresses, you decide what AUTH, MAIL FROM, RCPT TO, and DATA mean.

mailsmtp handles:

• the protocol - AUTH, MAIL FROM, RCPT TO, DATA, STARTTLS, PIPELINING
• streaming - receive gets a live io into the DATA stream, no buffering the whole message
• size limits - SIZE is advertised and enforced as DATA arrives
• smuggling protection - bare LF lines are rejected by default
• backpressure - concurrent DATA transfers are capped, with a queue and timeout
• hot reloading - swap the STARTTLS certificate without restarting

Plus:

• subclass-and-override hooks for every verb
• raise a typed error to choose the SMTP reply
• multi-listen across any number of host×port pairs
• injectable logger and live connection/processing counters

• Installation
• Getting Started
• Design
  • Role — server only
  • Hooks — subclass verbs
  • DATA — live reader into receive
• Reference
  • Hooks
  • Options
• Testing
• History
• Contributing
• License

Add this line to your application's Gemfile:

gem "mailsmtp"

Requires Ruby >= 3.3.4

Subclass MailSmtp::Server and override the hooks you care about.

require "mailsmtp"

class MyServer < MailSmtp::Server
  def connected(session)
    session.local_response = "mail.example.com ESMTP"
    session.helo_response = "mail.example.com"
  end

  def authenticate(session, username:, password:, authorization_id: "")
    raise MailSmtp::AuthenticationFailed unless username == "user" && password == "secret"
    username # becomes session.authorization_id when non-empty
  end

  def mail_from(session, address)
    address[/<([^>]*)>/, 1] || address # returned value is stored on the envelope
  end

  def rcpt_to(session, address)
    address[/<([^>]*)>/, 1] || address
  end

  def receive(session, io)
    # Prefer streaming — io.read materializes the whole message in memory.
    IO.copy_stream(io, storage_destination)
  end
end

And start it:

server = MyServer.new(
  host: "127.0.0.1",
  port: 2525,
  tls: nil,
  auth: :disabled,
  starttls: :optional,
  max_connections: 100,
  max_processings: 4,
  max_message_size: 10_485_760,
  max_recipients: 100,
  read_timeout: 300,
  write_timeout: 30,
  handshake_timeout: 30
)
server.start

Hot-swap the STARTTLS certificate without restarting:

server.tls = new_tls_context

Multi-listen: hosts: / ports: expand to every host×port pair.

mailsmtp is an SMTP server. Outbound submission (Net::SMTP, your MTA, Action Mailer) stays outside the gem.

Subclass MailSmtp::Server and override methods: authenticate, auth_mechanisms, mail_from, rcpt_to, receive, plus build_session / process_line when you need a custom session or command gate.

One server object owns policy; Session is connection state (envelope, auth), not a second interface you implement. Raise a MailSmtp::Error subclass to choose the SMTP reply.

After 354, the engine builds a DataReader over the socket (dot-unstuffing, SIZE, line limits) and calls receive(session, io). Prefer IO.copy_stream (or chunked reads); the engine drains through . then sends one reply — except when SIZE/MessageTooLarge (or the drain byte ceiling) forces a close after the error reply (no unbounded drain).

def receive(session, io)
  IO.copy_stream(io, storage_destination)
  # or: while (chunk = io.read(8192)); ...; end  — read(len) returns nil at EOF
end

SIZE / line-length failures raise a MailSmtp::Error from read / readpartial (not a short successful body). Mid-DATA disconnect raises ServiceUnavailable. If receive ignores the io, the reply still comes from the reader's failure after drain.

Raising a MailSmtp::Error subclass sends that SMTP reply to the client. Other exceptions during receive become a 451 (LocalError). Unexpected errors outside DATA still need cleanup (prefer raising a defined error).

starttls: :required requires a non-nil tls object. Per-IP connection caps are deferred for peers in proxy_hosts until PROXY rewrites the client address. Forced #stop aborts lingering sockets with RST (SO_LINGER 0). Inspect live load with connections_count / processings_count (and connections?).

bundle install
rake

View the changelog.

Everyone is encouraged to help improve this project:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

MIT. See LICENSE.