File: README — Documentation for midi-smtp-server (3.0.3)

MidiSmtpServer

The highly customizable ruby SMTP-Service library

-- Mail-Server, SMTP-Service, MTA, Email-Gateway & Router, Mail-Automation --

MidiSmtpServer

MidiSmtpServer is the highly customizable ruby SMTP-Server and SMTP-Service library with builtin support for AUTH and SSL/STARTTLS, 8BITMIME and SMTPUTF8, IPv4 and IPv6 and additional features.

As a library it is mainly designed to be integrated into your projects as serving a SMTP-Server service. The lib will do nothing with your mail and you have to create your own event functions to handle and operate on incoming mails. We are using this in conjunction with Mikel Lindsaar great Mail component (https://github.com/mikel/mail). Time to run your own SMTP-Server service.

Checkout all the features and improvements (3.0.1 Logging enhancement, 2.3.x Multiple ports and addresses, 2.2.x Encryption [StartTLS], 2.1.0 Authentication [AUTH], 2.1.1 significant speed improvement, etc.) and get more details from section changes and updates.

MidiSmtpServer is an extremely flexible library and almost any aspect of SMTP communications can be handled by deriving its events and using its configuration options.

Using the library

To derive your own SMTP-Server service with DATA processing simply do:

# Server class
class MySmtpd < MidiSmtpServer::Smtpd

  # get each message after DATA <message> .
  def on_message_data_event(ctx)
    # Output for debug
    logger.debug("[#{ctx[:envelope][:from]}] for recipient(s): [#{ctx[:envelope][:to]}]...")

    # Just decode message once to make sure, that this message ist readable
    @mail = Mail.read_from_string(ctx[:message][:data])

    # handle incoming mail, just show the message subject
    logger.debug(@mail.subject)
  end

end

Please checkout the source codes from Examples for working SMTP-Services.

Operation purposes

There is an endless field of application for SMTP services. You want to create your own SMTP Server as a mail gateway to clean up routed emails from spam and virus content. Incoming mails may be processed and handled native and by proper functions. A SMTP daemon can receive messages and forward them to a service like Slack, Trello, Redmine, Twitter, Facebook, Instagram and others.

This source code shows the example to receive messages via SMTP and store them to RabbitMQ (Message-Queue-Server) for subsequent processings etc.:

  # get each message after DATA <message> .
  def on_message_data_event(ctx)
    # Just decode message once to make sure, that this message ist readable
    @mail = Mail.read_from_string(ctx[:message])

    # Publish to rabbit
    @bunny_exchange.publish(@mail.to_s, :headers => { 'x-smtp' => @mail.header.to_s }, :routing_key => "to_queue")
  end

Installation

MidiSmtpServer is packaged as a RubyGem so that you can easily install by entering following at your command line:

gem install midi-smtp-server

Use the component in your project sources by:

require 'midi-smtp-server'

Library documentation

Read the MidiSmtpServer Documentation for a complete library documentation.

Reliable code

Since version 2.3 implementation and integration tests by minitest framework are added to this repository. While the implementation tests are mostly checking the components, the integration tests try to verify the correct exchange of messages for different scenarios. In addtion all sources are checked by rubocop to ensure they fit to the style guides.

You may run all rubocop tests through the rake helper:

  bundle exec rake rubocop

You may also run all tests through the rake helper:

  bundle exec rake test:all

or with more verbose output:

  bundle exec rake test:all v=1

To just run just a part of the tests, you may select the specs, unit or integration tests:

  bundle exec rake test:specs

To just run some selected (by regular expression) tests, you may use the T=filter option. The example will run only the tests and specs containing the word connections in their method_name or describe_text:

  bundle exec rake test:all v=1 T=connections

Be aware that the parameters and filter are case sensitive.

Style guide links

Changes and updates

We suggest everybody using MidiSmtpServer to switch at least to latest 2.3.y. or best to 3.x. The update is painless and mostly without any source code changes :sunglasses:

For upgrades from previous versions or outdated MiniSmtpServer gem you may follow the guides (see appendix) how to change your existing code to be compatible with the latest releases.

Latest release: 3.0.3 (2022-02-12)

Critical fix for thread safety (check issue 29)
Fix tests using net/smtp '>= 0.3.1'

Changelog history

A complete list of updates and features can be read in the CHANGELOG.

Upgrading from previous releases :small_red_triangle:

Checkout the Appendix Upgrade to get your code ready for the latest releases and read about any incompatibilities.

Gem Package

You may find, use and download the gem package on RubyGems.org.

Documentation

Project homepage - you will find a micro-site at Github

Class documentation - you will find a detailed description at RubyDoc

Library manual - you will find a manual at ReadTheDocs

Author & Credits

Author: Tom Freudenberg

MidiSmtpServer Class is inspired from MiniSmtpServer Class and code written by Aaron Gough and Peter Cooper