mailosaur 7.2.0 → 7.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 011e2ac28ac0877666e8773c40e40dc6d0a1a5af9f32aeb73da66d57bdb2b003
-  data.tar.gz: c6dc865d59c1cd2f93a59352a4652deef949673676241cca325d6d23904b72c6
+  metadata.gz: 056e993a519633fcca85156531e4eb18cc1643fa230d7f15f6239794b5529f97
+  data.tar.gz: de2d43526a0512c7f92882fa5b23ca0d462852f7b2123ada28e34c42b0ad6b9b
 SHA512:
-  metadata.gz: d226ef24c5af4e341d93ccb17f64f0f83788273958ce48aff5c815aaafd3fdc84bef7942355c1507f4d8014d6d42559180cb3d4ae873511610256929f8466dd7
-  data.tar.gz: afb69cdb68ef7f270dee406c34a6c7f576e58cb3bafbc4689edbd4fdcc725786e06a0f177ec0398ef425a76bb99ce9cdb0e6c3fa2aa83785ca36277bd782ea83
+  metadata.gz: f10d8c30b5b44f8a1fa19e2305599f8d5c48ab1e00e1c903cf4380d992e4c892b6a5e7637fe09b86016023545d70c357d5603802cdb6fb8e2169051f4ffa3e6d
+  data.tar.gz: b1a02d600af6526d11fffae86c94ea78c768a073489d3be996f803c943ba6f5a6223240933f2a6db07884fba239b633f95f87784b2d3ddb447c34b4a508805be

data/README.md

@@ -1,30 +1,291 @@
-# Mailosaur Ruby Client Library
+# [Mailosaur - Ruby library](https://mailosaur.com/) · [![](https://github.com/mailosaur/mailosaur-ruby/workflows/CI/badge.svg)](https://github.com/mailosaur/mailosaur-ruby/actions) 
 
-[Mailosaur](https://mailosaur.com) lets you automate email and SMS tests, like account verification and password resets, and integrate these into your CI/CD pipeline.
+Mailosaur lets you automate email and SMS tests as part of software development and QA.
 
-[![](https://github.com/mailosaur/mailosaur-ruby/workflows/CI/badge.svg)](https://github.com/mailosaur/mailosaur-ruby/actions)
+- **Unlimited test email addresses for all**  - every account gives users an unlimited number of test email addresses to test with.
+- **End-to-end (e2e) email and SMS testing** Allowing you to set up end-to-end tests for password reset emails, account verification processes and MFA/one-time passcodes sent via text message.
+- **Fake SMTP servers** Mailosaur also provides dummy SMTP servers to test with; allowing you to catch email in staging environments - preventing email being sent to customers by mistake.
 
-## Installation
+## Get Started
+
+This guide provides several key sections:
+
+  - [Get Started](#get-started)
+  - [Creating an account](#creating-an-account)
+  - [Test email addresses with Mailosaur](#test-email-addresses-with-mailosaur)
+  - [Find an email](#find-an-email)
+  - [Find an SMS message](#find-an-sms-message)
+  - [Testing plain text content](#testing-plain-text-content)
+  - [Testing HTML content](#testing-html-content)
+  - [Working with hyperlinks](#working-with-hyperlinks)
+  - [Working with attachments](#working-with-attachments)
+  - [Working with images and web beacons](#working-with-images-and-web-beacons)
+  - [Spam checking](#spam-checking)
+
+You can find the full [Mailosaur documentation](https://mailosaur.com/docs/) on the website.
+
+If you get stuck, just contact us at support@mailosaur.com.
+
+### Installation
 
 ```
 gem install mailosaur
 ```
 
-## Documentation
+Then import the library into your code. The value for `YOUR_API_KEY` is covered in the next step ([creating an account](#creating-an-account)):
+
+```ruby
+require 'mailosaur'
+mailosaur = Mailosaur::MailosaurClient.new("YOUR_API_KEY")
+```
+
+### API Reference
+
+This library is powered by the Mailosaur [email & SMS testing API](https://mailosaur.com/docs/api/). You can easily check out the API itself by looking at our [API reference documentation](https://mailosaur.com/docs/api/) or via our Postman or Insomnia collections:
+
+[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/6961255-6cc72dff-f576-451a-9023-b82dec84f95d?action=collection%2Ffork&collection-url=entityId%3D6961255-6cc72dff-f576-451a-9023-b82dec84f95d%26entityType%3Dcollection%26workspaceId%3D386a4af1-4293-4197-8f40-0eb49f831325)
+ [![Run in Insomnia}](https://insomnia.rest/images/run.svg)](https://insomnia.rest/run/?label=Mailosaur&uri=https%3A%2F%2Fmailosaur.com%2Finsomnia.json)
+
+## Creating an account
+
+Create a [free trial account](https://mailosaur.com/app/signup) for Mailosaur via the website.
+
+Once you have this, navigate to the [API tab](https://mailosaur.com/app/project/api) to find the following values:
+
+- **Server ID** - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
+- **Server Domain** - Every server has its own domain name. You'll need this to send email to your server.
+- **API Key** - You can create an API key per server (recommended), or an account-level API key to use across your whole account. [Learn more about API keys](https://mailosaur.com/docs/managing-your-account/api-keys/).
 
-Please see the [Ruby client reference](https://mailosaur.com/docs/email-testing/ruby/client-reference/) for the most up-to-date documentation.
+## Test email addresses with Mailosaur
 
-## Usage
+Mailosaur gives you an **unlimited number of test email addresses** - with no setup or coding required!
 
-example.rb
+Here's how it works:
+
+* When you create an account, you are given a server.
+* Every server has its own **Server Domain** name (e.g. `abc123.mailosaur.net`)
+* Any email address that ends with `@{YOUR_SERVER_DOMAIN}` will work with Mailosaur without any special setup. For example:
+  * `build-423@abc123.mailosaur.net`
+  * `john.smith@abc123.mailosaur.net`
+  * `rAnDoM63423@abc123.mailosaur.net`
+* You can create more servers when you need them. Each one will have its own domain name.
+
+***Can't use test email addresses?** You can also [use SMTP to test email](https://mailosaur.com/docs/email-testing/sending-to-mailosaur/#sending-via-smtp). By connecting your product or website to Mailosaur via SMTP, Mailosaur will catch all email your application sends, regardless of the email address.*
+
+## Find an email
+
+In automated tests you will want to wait for a new email to arrive. This library makes that easy with the `messages.get` method. Here's how you use it:
 
 ```ruby
-require "mailosaur"
-mailosaur = Mailosaur::MailosaurClient.new("YOUR_API_KEY")
+require 'mailosaur'
+
+mailosaur = Mailosaur::MailosaurClient.new("API_KEY")
+
+# See https://mailosaur.com/app/project/api
+server_id = "abc123"
+server_domain = "abc123.mailosaur.net"
+
+criteria = Mailosaur::Models::SearchCriteria.new()
+criteria.sent_to = "anything@" + server_domain
+
+email = mailosaur.messages.get(server_id, criteria)
+
+puts(email.subject) # "Hello world!"
+```
+
+### What is this code doing?
+
+1. Sets up an instance of `MailosaurClient` with your API key.
+2. Waits for an email to arrive at the server with ID `abc123`.
+3. Outputs the subject line of the email.
+
+## Find an SMS message
+
+**Important:** Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.
+
+If your account has [SMS testing](https://mailosaur.com/sms-testing/) enabled, you can reserve phone numbers to test with, then use the Mailosaur API in a very similar way to when testing email:
+
+```ruby
+require 'mailosaur'
+
+mailosaur = Mailosaur::MailosaurClient.new("API_KEY")
+
+server_id = "abc123"
+
+criteria = Mailosaur::Models::SearchCriteria.new()
+criteria.sent_to = "4471235554444"
+
+sms = mailosaur.messages.get(server_id, criteria)
+
+puts(sms.text.body)
+```
+
+## Testing plain text content
+
+Most emails, and all SMS messages, should have a plain text body. Mailosaur exposes this content via the `text.body` property on an email or SMS message:
+
+```ruby
+puts(message.text.body) # "Hi Jason, ..."
+
+if message.text.body.include? "Jason"
+  puts("Email contains 'Jason'")
+end
+```
+
+### Extracting verification codes from plain text
+
+You may have an email or SMS message that contains an account verification code, or some other one-time passcode. You can extract content like this using a simple regex.
+
+Here is how to extract a 6-digit numeric code:
+
+```ruby
+puts(message.text.body) # "Your access code is 243546."
+
+match = message.text.body.match(/([0-9]{6})/)
+puts(match[0]) # "243546"
+```
+
+[Read more](https://mailosaur.com/docs/test-cases/text-content/)
+
+## Testing HTML content
+
+Most emails also have an HTML body, as well as the plain text content. You can access HTML content in a very similar way to plain text:
+
+```ruby
+puts(message.html.body) # "<html><head ..."
+```
+
+### Working with HTML using nokogiri
+
+If you need to traverse the HTML content of an email. For example, finding an element via a CSS selector, you can use the [nokogiri](https://rubygems.org/gems/nokogiri) library.
+
+```sh
+gem install nokogiri
+```
+
+```ruby
+require 'nokogiri'
+
+# ...
+
+@doc = Nokogiri::HTML(message.html.body)
+el = @doc.css(".verification-code")
+
+verification_code = el.text
+
+puts verification_code # "542163"
+```
+
+[Read more](https://mailosaur.com/docs/test-cases/html-content/)
+
+## Working with hyperlinks
+
+When an email is sent with an HTML body, Mailosaur automatically extracts any hyperlinks found within anchor (`<a>`) and area (`<area>`) elements and makes these viable via the `html.links` array.
+
+Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
+
+```ruby
+# How many links?
+puts(message.html.links.length) # 2
+
+first_link = message.html.links[0]
+puts(first_link.text) # "Google Search"
+puts(first_link.href) # "https://www.google.com/"
+```
+
+**Important:** To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with `<a>` or `<area>` tags.
+
+### Links in plain text (including SMS messages)
+
+Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
+
+```ruby
+# How many links?
+puts(message.text.links.length) # 2
+
+first_link = message.text.links[0]
+puts(first_link.href) # "https://www.google.com/"
+```
+
+## Working with attachments
+
+If your email includes attachments, you can access these via the `attachments` property:
+
+```ruby
+# How many attachments?
+puts(message.attachments.length) # 2
+```
+
+Each attachment contains metadata on the file name and content type:
+
+```ruby
+first_attachment = message.attachments[0]
+puts(first_attachment.file_name) # "contract.pdf"
+puts(first_attachment.content_type) # "application/pdf"
+```
+
+The `length` property returns the size of the attached file (in bytes):
+
+```ruby
+first_attachment = message.attachments[0]
+puts(first_attachment.length) # 4028
+```
+
+## Working with images and web beacons
+
+The `html.images` property of a message contains an array of images found within the HTML content of an email. The length of this array corresponds to the number of images found within an email:
+
+```ruby
+# How many images in the email?
+puts(message.html.images.length) # 1
+```
+
+### Remotely-hosted images
+
+Emails will often contain many images that are hosted elsewhere, such as on your website or product. It is recommended to check that these images are accessible by your recipients.
+
+All images should have an alternative text description, which can be checked using the `alt` attribute.
+
+```ruby
+image = message.html.images[0]
+puts(image.alt) # "Hot air balloon"
+```
+
+### Triggering web beacons
+
+A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
+
+Because a web beacon is simply another form of remotely-hosted image, you can use the `src` attribute to perform an HTTP request to that address:
+
+```ruby
+image = message.html.images[0]
+puts(image.src) # "https://example.com/s.png?abc123"
+
+# Make an HTTP call to trigger the web beacon
+uri = URI(image.src)
+Net::HTTP.start(uri.host, uri.port,
+:use_ssl => uri.scheme == 'https') do |http|
+request = Net::HTTP::Get.new uri
+
+response = http.request request # Net::HTTPResponse object
+puts(response.code) # 200
+end
+```
+
+## Spam checking
+
+You can perform a [SpamAssassin](https://spamassassin.apache.org/) check against an email. The structure returned matches the [spam test object](https://mailosaur.com/docs/api/#spam):
+
+```ruby
+result = mailosaur.analysis.spam(message.id)
 
-result = mailosaur.servers.list()
+puts(result.score) # 0.5
 
-print("You have a server called: " + result.items[0].name)
+for r in result.spam_filter_results.spam_assassin do
+  puts(r.rule)
+  puts(r.description)
+  puts(r.score)
+end
 ```
 
 ## Development

data/lib/Mailosaur/models/usage_account_limit.rb

@@ -0,0 +1,16 @@
+module Mailosaur
+  module Models
+    class UsageAccountLimit < BaseModel
+      def initialize(data = {})
+        @limit = data['limit']
+        @current = data['current']
+      end
+
+      # @return [Integer] The limit.
+      attr_accessor :limit
+
+      # @return [Integer] The current usage.
+      attr_accessor :current
+    end
+  end
+end

data/lib/Mailosaur/models/usage_account_limits.rb

@@ -0,0 +1,24 @@
+module Mailosaur
+  module Models
+    class UsageAccountLimits < BaseModel
+      def initialize(data = {})
+        @servers = Mailosaur::Models::UsageAccountLimit.new(data['servers'])
+        @users = Mailosaur::Models::UsageAccountLimit.new(data['users'])
+        @email = Mailosaur::Models::UsageAccountLimit.new(data['email'])
+        @sms = Mailosaur::Models::UsageAccountLimit.new(data['sms'])
+      end
+
+      # @return [UsageAccountLimit]
+      attr_accessor :servers
+
+      # @return [UsageAccountLimit]
+      attr_accessor :users
+
+      # @return [UsageAccountLimit]
+      attr_accessor :email
+
+      # @return [UsageAccountLimit]
+      attr_accessor :sms
+    end
+  end
+end

data/lib/Mailosaur/models/usage_transaction.rb

@@ -0,0 +1,20 @@
+module Mailosaur
+  module Models
+    class UsageTransaction < BaseModel
+      def initialize(data = {})
+        @timestamp = DateTime.parse(data['timestamp'])
+        @email = data['email']
+        @sms = data['sms']
+      end
+
+      # @return [DateTime] The datetime that this transaction occurred.
+      attr_accessor :timestamp
+
+      # @return [Integer] The count of emails.
+      attr_accessor :email
+
+      # @return [Integer] The count of SMS messages.
+      attr_accessor :sms
+    end
+  end
+end

data/lib/Mailosaur/models/usage_transaction_list_result.rb

@@ -0,0 +1,13 @@
+module Mailosaur
+  module Models
+    class UsageTransactionListResult < BaseModel
+      def initialize(data = {})
+        @items = []
+        (data['items'] || []).each do |i| @items << Mailosaur::Models::UsageTransaction.new(i) end
+      end
+
+      # @return [Array<UsageTransaction>] The individual transactions the result.
+      attr_accessor :items
+    end
+  end
+end

data/lib/Mailosaur/servers.rb

@@ -60,6 +60,23 @@ module Mailosaur
       Mailosaur::Models::Server.new(model)
     end
 
+    #
+    # Retrieve server password
+    #
+    # Retrieves the password for use with SMTP and POP3 for a single server.
+    # Simply supply the unique identifier for the required server.
+    #
+    # @param id [String] The identifier of the server.
+    #
+    # @return [String] Server password.
+    #
+    def get_password(id)
+      response = conn.get 'api/servers/' + id + '/password'
+      @handle_http_error.call(response) unless response.status == 200
+      model = JSON.load(response.body)
+      model['value']
+    end
+
     #
     # Update a server
     #

data/lib/Mailosaur/usage.rb

@@ -0,0 +1,41 @@
+module Mailosaur
+  class Usage
+    #
+    # Creates and initializes a new instance of the Usage class.
+    # @param client connection.
+    #
+    def initialize(conn, handle_http_error)
+      @conn = conn
+      @handle_http_error = handle_http_error
+    end
+
+    # @return [Connection] the client connection.
+    attr_reader :conn
+
+    #
+    # Retrieve account usage limits.
+    #
+    # Details the current limits and usage for your account.
+    #
+    # @return [UsageAccountLimits] operation results.
+    #
+    def limits
+      response = conn.get 'api/usage/limits'
+      @handle_http_error.call(response) unless response.status == 200
+      model = JSON.load(response.body)
+      Mailosaur::Models::UsageAccountLimits.new(model)
+    end
+
+    #
+    # List account transactions. Retrieves the last 31 days of transactional usage.
+    #
+    # @return [UsageTransactionListResult] operation results.
+    #
+    def transactions
+      response = conn.get 'api/usage/transactions'
+      @handle_http_error.call(response) unless response.status == 200
+      model = JSON.load(response.body)
+      Mailosaur::Models::UsageTransactionListResult.new(model)
+    end
+  end
+end

data/lib/Mailosaur/version.rb

@@ -1,3 +1,3 @@
 module Mailosaur
-    VERSION = '7.2.0'.freeze
+    VERSION = '7.3.2'.freeze
 end

data/lib/mailosaur.rb

@@ -13,6 +13,7 @@ module Mailosaur
   autoload :Files,                                              'Mailosaur/files.rb'
   autoload :Messages,                                           'Mailosaur/messages.rb'
   autoload :Servers,                                            'Mailosaur/servers.rb'
+  autoload :Usage,                                              'Mailosaur/usage.rb'
   autoload :MailosaurError,                                     'Mailosaur/mailosaur_error.rb'
 
   module Models
@@ -33,6 +34,10 @@ module Mailosaur
     autoload :ServerListResult,                                   'Mailosaur/models/server_list_result.rb'
     autoload :SpamFilterResults,                                  'Mailosaur/models/spam_filter_results.rb'
     autoload :ServerCreateOptions,                                'Mailosaur/models/server_create_options.rb'
+    autoload :UsageAccountLimits,                                 'Mailosaur/models/usage_account_limits.rb'
+    autoload :UsageAccountLimit,                                  'Mailosaur/models/usage_account_limit.rb'
+    autoload :UsageTransactionListResult,                         'Mailosaur/models/usage_transaction_list_result.rb'
+    autoload :UsageTransaction,                                   'Mailosaur/models/usage_transaction.rb'
     autoload :BaseModel,                                          'Mailosaur/models/base_model.rb'
   end
 
@@ -67,6 +72,11 @@ module Mailosaur
       @servers ||= Servers.new(connection, method(:handle_http_error))
     end
 
+    # @return [Usage] usage
+    def usage
+      @usage ||= Usage.new(connection, method(:handle_http_error))
+    end
+
     private
 
     def connection

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: mailosaur
 version: !ruby/object:Gem::Version
-  version: 7.2.0
+  version: 7.3.2
 platform: ruby
 authors:
 - Mailosaur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-14 00:00:00.000000000 Z
+date: 2021-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: mail
   requirement: !ruby/object:Gem::Requirement
@@ -175,8 +175,13 @@ files:
 - lib/Mailosaur/models/spam_analysis_result.rb
 - lib/Mailosaur/models/spam_assassin_rule.rb
 - lib/Mailosaur/models/spam_filter_results.rb
+- lib/Mailosaur/models/usage_account_limit.rb
+- lib/Mailosaur/models/usage_account_limits.rb
+- lib/Mailosaur/models/usage_transaction.rb
+- lib/Mailosaur/models/usage_transaction_list_result.rb
 - lib/Mailosaur/module_definition.rb
 - lib/Mailosaur/servers.rb
+- lib/Mailosaur/usage.rb
 - lib/Mailosaur/version.rb
 - lib/mailosaur.rb
 homepage: https://mailosaur.com/
@@ -203,7 +208,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
 summary: The Mailosaur Ruby library