truemail-client gem - Truemail web API client library for Ruby.

Actual and maintainable documentation 📚 for developers is living here.

• Requirements
• Installation
• Usage
  • Setting global configuration
  • Establishing connection with Truemail API
  • Checking server health status
  • Additional features
• Truemail family
• Contributing
• License
• Code of Conduct
• Versioning
• Changelog

Ruby MRI 2.5.0+

Add this line to your application's Gemfile:

gem 'truemail-client'

And then execute:

bundle

Or install it yourself as:

gem install truemail-client

To have an access for Truemail::Client you must configure it first as in the example below:

require 'truemail/client'

Truemail::Client.configure do |config|
  # Required parameter (String). It should be a hostname or an ip address where Truemail server runs
  config.host = 'example.com'

  # Required parameter (String). It should be valid Truemail server access token
  config.token = 'token'

  # Optional parameter (Boolean). By default it is equal false
  config.secure_connection = true

  # Optional parameter (Integer). By default it is equal 9292
  config.port = 80
end

After successful configuration, you can establish connection with Truemail server.

Truemail::Client.validate('admin@bestweb.com.ua')

{
  "date": "2020-02-26 17:00:56 +0200",
  "email": "admin@bestweb.com.ua",
  "validation_type": "smtp",
  "success": true,
  "errors": null,
  "smtp_debug": null,
  "configuration": {
    "validation_type_by_domain": null,
    "whitelist_validation": false,
    "whitelisted_domains": null,
    "blacklisted_domains": null,
    "blacklisted_mx_ip_addresses": null,
    "dns": null,
    "smtp_safe_check": false,
    "email_pattern": "default gem value",
    "smtp_error_body_pattern": "default gem value",
    "not_rfc_mx_lookup_flow": false
  }
}

Truemail::Client.validate always returns JSON data. If something goes wrong you will receive JSON with error details:

{
  "truemail_client_error": "error details"
}

After successful configuration, you can check health-status of Truemail server.

Truemail::Client.server_healthy?

=> true

After successful configuration, you can read current Truemail::Client configuration instance anywhere in your application.

Truemail::Client.configuration
=> #<Truemail::Client::Configuration:0x000055eafc588878
  @host="example.com",
  @port=80,
  @secure_connection=true,
  @token="token">

Truemail::Client.configuration.port = 8080
=> 8080

Truemail::Client.configuration
=> #<Truemail::Client::Configuration:0x000055eafc588878
  @host="example.com",
  @port=8080,
  @secure_connection=true,
  @token="token">

Also you can reset Truemail::Client configuration.

Truemail::Client.reset_configuration!
=> nil
Truemail::Client.configuration
=> nil

All Truemail solutions: https://truemail-rb.org

Bug reports and pull requests are welcome on GitHub at https://github.com/truemail-rb/truemail-ruby-client. 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.

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

truemail-ruby-client uses Semantic Versioning 2.0.0