mailosaur 7.0.2 → 7.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 798ce47acf047126597a038b0bdb2297f4a4806145674ee116cefcb1e31dd556
-  data.tar.gz: 5595c1400c4e16d1f0f1f75e44f027809b95d89817890d54695240e053f63a13
+  metadata.gz: 9e326500621113c758df3e3d9fbc06778a9799a73e9d825de967c85c4f905d5d
+  data.tar.gz: f3110a0807155e33a531c655eeaeb1f05397ab501ae8a273ec6cbeff40c4adc7
 SHA512:
-  metadata.gz: 1a193b027b089135e3855ae44abe60c777e3addca743ae48620577aa79b08877d31aa01497381055e64178ce0c848f23530041d6ff70d573fd6054556fdec7c0
-  data.tar.gz: 71e18e02a530719f12cc506ed6bafda93c0127e8c37f5ac26345659506427453c11e540dc53feafc99b4dd21cbb607a6c07b08ed8229bfa5ec46de5e91f1f011
+  metadata.gz: ff7ee803eb0cc60fa0bcf7ad2f94f0103f2ebd94a056512fdb093e84f28db9cf6a00d2d6f8640fd4d439e1c120b314a05af7f37b7efda3c9ccf8b3281652caab
+  data.tar.gz: e807b3f423236e619b15e8cf3a4d95399531648b18f99595d31e381bc20862a7aa13286ccb686a82df99a49ff3e6934026a91d95315e1d80fba62829e7ccb5a6

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/server.rb

@@ -3,21 +3,15 @@ module Mailosaur
     class Server < BaseModel
       def initialize(data = {})
         @id = data['id']
-        @password = data['password']
         @name = data['name']
         @users = data['users']
         @messages = data['messages']
-        @forwarding_rules = []
-        (data['forwardingRules'] || []).each do |i| @forwarding_rules << Mailosaur::Models::ForwardingRule.new(i) end
       end
 
       # @return [String] Unique identifier for the server. Used as username for
       # SMTP/POP3 authentication.
       attr_accessor :id
 
-      # @return [String] SMTP/POP3 password.
-      attr_accessor :password
-
       # @return [String] A name used to identify the server.
       attr_accessor :name
 
@@ -26,10 +20,6 @@ module Mailosaur
 
       # @return [Integer] The number of messages currently in the server.
       attr_accessor :messages
-
-      # @return [Array<ForwardingRule>] The rules used to manage email
-      # forwarding for this server.
-      attr_accessor :forwarding_rules
     end
   end
 end

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
     #
@@ -92,8 +109,8 @@ module Mailosaur
     end
 
     def generate_email_address(server)
-      host = ENV['MAILOSAUR_SMTP_HOST'] || 'mailosaur.io'
-      '%s.%s@%s' % [SecureRandom.hex(3), server, host]
+      host = ENV['MAILOSAUR_SMTP_HOST'] || 'mailosaur.net'
+      '%s@%s.%s' % [SecureRandom.hex(3), server, host]
     end
   end
 end

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.0.2'.freeze
+    VERSION = '7.3.1'.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
@@ -27,13 +28,16 @@ module Mailosaur
     autoload :MessageListResult,                                  'Mailosaur/models/message_list_result.rb'
     autoload :Attachment,                                         'Mailosaur/models/attachment.rb'
     autoload :SearchCriteria,                                     'Mailosaur/models/search_criteria.rb'
-    autoload :ForwardingRule,                                     'Mailosaur/models/forwarding_rule.rb'
     autoload :MessageContent,                                     'Mailosaur/models/message_content.rb'
     autoload :Server,                                             'Mailosaur/models/server.rb'
     autoload :Link,                                               'Mailosaur/models/link.rb'
     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
 
@@ -68,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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailosaur
 version: !ruby/object:Gem::Version
-  version: 7.0.2
+  version: 7.3.1
 platform: ruby
 authors:
 - Mailosaur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-20 00:00:00.000000000 Z
+date: 2021-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -159,7 +159,6 @@ files:
 - lib/Mailosaur/messages.rb
 - lib/Mailosaur/models/attachment.rb
 - lib/Mailosaur/models/base_model.rb
-- lib/Mailosaur/models/forwarding_rule.rb
 - lib/Mailosaur/models/image.rb
 - lib/Mailosaur/models/link.rb
 - lib/Mailosaur/models/message.rb
@@ -176,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/
@@ -204,7 +208,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.15
 signing_key: 
 specification_version: 4
 summary: The Mailosaur Ruby library

data/lib/Mailosaur/models/forwarding_rule.rb

@@ -1,25 +0,0 @@
-module Mailosaur
-  module Models
-    class ForwardingRule < BaseModel
-      def initialize(data = {})
-        @field = data['field']
-        @operator = data['operator']
-        @value = data['value']
-        @forward_to = data['forwardTo']
-      end
-
-      # @return [Enum] Possible values include: 'from', 'to', 'subject'
-      attr_accessor :field
-
-      # @return [Enum] Possible values include: 'endsWith', 'startsWith',
-      # 'contains'
-      attr_accessor :operator
-
-      # @return [String]
-      attr_accessor :value
-
-      # @return [String]
-      attr_accessor :forward_to
-    end
-  end
-end