The project is in a healthy, maintained state
💎 Ruby SMTP mock. Mimic any SMTP server behaviour for your test environment.


~> 2.21
~> 13.0, >= 13.0.6
~> 3.11


 Project Readme

Ruby SmtpMock - mimic any 📤 SMTP server behaviour for your test environment with fake SMTP server

Maintainability Test Coverage CircleCI Gem Version Downloads GitHub Contributor Covenant

💎 Ruby SMTP mock - flexible Ruby wrapper over smtpmock. Mimic any 📤 SMTP server behaviour for your test environment and even more.

Table of Contents

  • Features
  • Requirements
  • Installation
  • Usage
    • Dependency manager
      • Available flags
    • DSL
      • Available server options
      • Example of usage
    • RSpec integration
      • SmtpMock RSpec helper
      • SmtpMock RSpec interface
  • Contributing
  • License
  • Code of Conduct
  • Credits
  • Versioning
  • Changelog


  • Ability to handle configurable behaviour and life cycles of SMTP mock server(s)
  • Dynamic/manual port assignment
  • Test framework agnostic (it's PORO, so you can use it outside of RSpec, Test::Unit or MiniTest)
  • Simple and intuitive DSL
  • RSpec integration out of the box
  • Includes easy system dependency manager


Ruby MRI 2.5.0+


Add this line to your application's Gemfile:

group :development, :test do
  gem 'smtp_mock', require: false

And then execute:

$ bundle

Or install it yourself as:

$ gem install smtp_mock

Then install smtpmock as system dependency:

$ bundle exec smtp_mock -i ~


Dependency manager

This gem includes easy system dependency manager. Run bundle exec smtp_mock with options for manage smtpmock system dependency.

Available flags

Flag Description Example of usage
-s, --sudo Run command as sudo bundle exec smtp_mock -s -i ~
-i, --install=PATH Install smtpmock to the existing path bundle exec smtp_mock -i ~/existent_dir
-u, --uninstall Uninstall smtpmock bundle exec smtp_mock -u
-g, --upgrade Upgrade to latest version of smtpmock bundle exec smtp_mock -g
-v, --version Prints current version of smtpmock bundle exec smtp_mock -v
-h, --help Prints help bundle exec smtp_mock -h


Available server options

Example of usage kwarg Description
host: '' Host address where smtpmock will run. It's equal to by default
port: 2525 Server port number. If not specified it will be assigned dynamically
log: true Enables log server activity. Disabled by default
session_timeout: 60 Session timeout in seconds. It's equal to 30 seconds by default
shutdown_timeout: 5 Graceful shutdown timeout in seconds. It's equal to 1 second by default
fail_fast: true Enables fail fast scenario. Disabled by default
blacklisted_helo_domains: %w[] Blacklisted HELO domains
blacklisted_mailfrom_emails: %w[] Blacklisted MAIL FROM emails
blacklisted_rcptto_emails: %w[] blacklisted RCPT TO emails
not_registered_emails: %w[] Not registered (non-existent) RCPT TO emails
msg_size_limit: 42 Message body size limit in bytes. It's equal to 10485760 bytes by default
msg_greeting: 'Greeting message' Custom server greeting message
msg_invalid_cmd: 'Invalid command message' Custom invalid command message
msg_invalid_cmd_helo_sequence: 'Invalid command HELO sequence message' Custom invalid command HELO sequence message
msg_invalid_cmd_helo_arg: 'Invalid command HELO argument message' Custom invalid command HELO argument message
msg_helo_blacklisted_domain: 'Blacklisted domain message' Custom HELO blacklisted domain message
msg_helo_received: 'HELO received message' Custom HELO received message
msg_invalid_cmd_mailfrom_sequence: 'Invalid command MAIL FROM sequence message' Custom invalid command MAIL FROM sequence message
msg_invalid_cmd_mailfrom_arg: 'Invalid command MAIL FROM argument message' Custom invalid command MAIL FROM argument message
msg_mailfrom_blacklisted_email: 'Blacklisted email message' Custom MAIL FROM blacklisted email message
msg_mailfrom_received: 'MAIL FROM received message' Custom MAIL FROM received message
msg_invalid_cmd_rcptto_sequence: 'Invalid command RCPT TO sequence message' Custom invalid command RCPT TO sequence message
msg_invalid_cmd_rcptto_arg: 'Invalid command RCPT TO argument message' Custom invalid command RCPT TO argument message
msg_rcptto_not_registered_email: 'Not registered email message' Custom RCPT TO not registered email message
msg_rcptto_blacklisted_email: 'Blacklisted email message' Custom RCPT TO blacklisted email message
msg_rcptto_received: 'RCPT TO received message' Custom RCPT TO received message
msg_invalid_cmd_data_sequence: 'Invalid command DATA sequence message' Custom invalid command DATA sequence message
msg_data_received: 'DATA received message' Custom DATA received message
msg_msg_size_is_too_big: 'Message size is too big' Custom size is too big message
msg_msg_received: 'Message has been received' Custom received message body message
msg_quit_cmd: 'Quit command message' Custom quit command message

Example of usage

# Public SmtpMock interface
# Without kwargs creates SMTP mock server with default behaviour.
# A free port for server will be randomly assigned in the range
# from 49152 to 65535. Returns current smtp mock server instance
smtp_mock_server = SmtpMock.start_server(not_registered_emails: %w[]) # => SmtpMock::Server instance

# returns current smtp mock server port
smtp_mock_server.port # => 55640

# returns current smtp mock server port # => 38195

# returns current smtp mock server version
smtp_mock_server.version # => '1.5.2'

# interface for graceful shutdown current smtp mock server
smtp_mock_server.stop # => true

# interface for force shutdown current smtp mock server
smtp_mock_server.stop! # => true

# interface to check state of current smtp mock server
# returns true if server is running, otherwise returns false # => true

# returns list of running smtp mock servers
SmtpMock.running_servers # => [SmtpMock::Server instance]

# interface to stop all running smtp mock servers
SmtpMock.stop_running_servers! # => true

RSpec integration

Require this either in your Gemfile or in RSpec's support scripts. So either:

# Gemfile

group :test do
  gem 'rspec'
  gem 'smtp_mock', require: 'smtp_mock/test_framework/rspec'


# spec/support/config/smtp_mock.rb

require 'smtp_mock/test_framework/rspec'

SmtpMock RSpec helper

Just add SmtpMock::TestFramework::RSpec::Helper if you wanna use shortcut smtp_mock_server for SmtpMock server instance inside of your RSpec.describe blocks:

# spec/support/config/smtp_mock.rb

RSpec.configure do |config|
  config.include SmtpMock::TestFramework::RSpec::Helper
# your awesome smtp_client_spec.rb

RSpec.describe SmtpClient do
  subject(:smtp_response) do
      host: 'localhost',
      port: smtp_mock_server.port,
      mailfrom: mailfrom,
      rcptto: rcptto,
      message: message

  let(:mailfrom) { '' }
  let(:rcptto) { '' }
  let(:message) { 'Email message context' }
  let(:expected_response_message) { '250 Custom successful response' }

  before { smtp_mock_server(msg_msg_received: expected_response_message) }

  it do
    expect(smtp_response).to be_success
    expect(smtp_response).to have_status(expected_response_status)
    expect(smtp_response).to have_message_context(expected_response_message)

SmtpMock RSpec interface

If you won't use SmtpMock::TestFramework::RSpec::Helper you can use SmtpMock::TestFramework::RSpec::Interface directly instead:

SmtpMock::TestFramework::RSpec::Interface.start_server  # creates and runs SmtpMock server instance
SmtpMock::TestFramework::RSpec::Interface.stop_server!  # stops and clears current SmtpMock server instance
SmtpMock::TestFramework::RSpec::Interface.clear_server! # clears current SmtpMock server instance


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. Please check the open tickets. Be sure to follow Contributor Code of Conduct below and our Contributing Guidelines.


The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the SmtpMock project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.



SmtpMock uses Semantic Versioning 2.0.0