mailosaur 8.1.0 → 8.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f9e68987fc63770ca61c94a5091b02ea932bb765ea6dfa1d2d3ca8603e58867
-  data.tar.gz: 8683c7bb7ffe561fc491867bb2000437cd3b0541cec1c738d9733c649c6c2d1d
+  metadata.gz: 073b2f6c745fe6ad8d815c0039bfcc8a39547a805c6615a00b037ca1ec415760
+  data.tar.gz: e6427526ae18e2bb269ec25a37149e4f74c2b1ef36d4b71dc13f6b1e70f98bc4
 SHA512:
-  metadata.gz: abb3db223ad672d31099e11284a928679c3a3c9db15b9e727c2fbd68119a23fe424bd75116b54b35c6a1b25ce9edb47f7a956baf444835b626a9acf904824bf0
-  data.tar.gz: 7a556665627605e074ce413a02be0d839032454445e5592de4367ee1d05707c193205726940a20545edd752926b277da7801e6b1dac9db14b0f738402110a065
+  metadata.gz: 886ccbcd88720e84729cbad7259d4a71436610710e7123ca1f5b4993852a8721ce4ba6a7d55849cbeb8d058f8e5098e3c610b97d08651b6c8791d847e6f6fbd1
+  data.tar.gz: d24a3505d18503da0a53790e0237c93e74a744657db5aeba4ae47e7936b61fadf6aa4771ff67bc0c355762f83f425fc4bd08ca09f2fcbb6a1eceb7af236dbe24

data/README.md

@@ -10,21 +10,32 @@ Mailosaur lets you automate email and SMS tests as part of software development
 
 This guide provides several key sections:
 
+- [Mailosaur - Ruby library · ](#mailosaur---ruby-library--)
   - [Get Started](#get-started)
-  - [Installation](#installation)
-  - [Set your API key](#set-your-api-key)
-  - [Create your code](#create-your-code)
-  - [API Reference](#api-reference)
+    - [Installation](#installation)
+    - [Set your API key](#set-your-api-key)
+    - [Create your code](#create-your-code)
+    - [API Reference](#api-reference)
   - [Creating an account](#creating-an-account)
   - [Test email addresses with Mailosaur](#test-email-addresses-with-mailosaur)
   - [Find an email](#find-an-email)
+    - [What is this code doing?](#what-is-this-code-doing)
+    - [My email wasn't found](#my-email-wasnt-found)
   - [Find an SMS message](#find-an-sms-message)
   - [Testing plain text content](#testing-plain-text-content)
+    - [Extracting verification codes from plain text](#extracting-verification-codes-from-plain-text)
   - [Testing HTML content](#testing-html-content)
+    - [Working with HTML using Nokogiri](#working-with-html-using-nokogiri)
   - [Working with hyperlinks](#working-with-hyperlinks)
+    - [Links in plain text (including SMS messages)](#links-in-plain-text-including-sms-messages)
   - [Working with attachments](#working-with-attachments)
+    - [Writing an attachment to disk](#writing-an-attachment-to-disk)
   - [Working with images and web beacons](#working-with-images-and-web-beacons)
+    - [Remotely-hosted images](#remotely-hosted-images)
+    - [Triggering web beacons](#triggering-web-beacons)
   - [Spam checking](#spam-checking)
+  - [Development](#development)
+  - [Contacting us](#contacting-us)
 
 You can find the full [Mailosaur documentation](https://mailosaur.com/docs/) on the website.
 
@@ -32,7 +43,7 @@ If you get stuck, just contact us at support@mailosaur.com.
 
 ### Installation
 
-```
+```sh
 gem install mailosaur
 ```
 
@@ -46,11 +57,11 @@ export MAILOSAUR_API_KEY='your-api-key-here'
 
 ### Create your code
 
-Then import the library into your code:
+Now import the library and create a client:
 
 ```ruby
 require 'mailosaur'
-mailosaur = Mailosaur::MailosaurClient.new()
+mailosaur = Mailosaur::MailosaurClient.new
 ```
 
 ### API Reference
@@ -58,17 +69,17 @@ mailosaur = Mailosaur::MailosaurClient.new()
 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)
+ [![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:
+To start testing you'll need three things:
 
-- **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/).
+- **API key** - [manage API keys within the Mailosaur Dashboard](https://mailosaur.com/app/keys). You can scope a key to a single inbox (server) — recommended — or create an account-level key. [Learn more about API keys](https://mailosaur.com/docs/managing-your-account/api-keys/).
+- **Inbox (server) domain** - open [your inbox](https://mailosaur.com/app/servers/default) (server) within the Mailosaur Dashboard to see its domain name (e.g. `abc123.mailosaur.net`). You'll need this to send email to the inbox (server).
+- **Inbox (server) ID** - the first part of the inbox (server) domain. For `abc123.mailosaur.net` the ID is `abc123`. You need this whenever you interact with the inbox (server) via the API.
 
 ## Test email addresses with Mailosaur
 
@@ -76,13 +87,13 @@ Mailosaur gives you an **unlimited number of test email addresses** - with no se
 
 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`)
+* When you create an account, you are given an inbox (server).
+* Every inbox (server) has its own 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.
+* You can create more inboxes (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.*
 
@@ -93,13 +104,12 @@ In automated tests you will want to wait for a new email to arrive. This library
 ```ruby
 require 'mailosaur'
 
-mailosaur = Mailosaur::MailosaurClient.new()
+mailosaur = Mailosaur::MailosaurClient.new
 
-# See https://mailosaur.com/app/project/api
 server_id = "abc123"
 server_domain = "abc123.mailosaur.net"
 
-criteria = Mailosaur::Models::SearchCriteria.new()
+criteria = Mailosaur::Models::SearchCriteria.new
 criteria.sent_to = "anything@" + server_domain
 
 email = mailosaur.messages.get(server_id, criteria)
@@ -109,10 +119,27 @@ puts(email.subject) # "Hello world!"
 
 ### What is this code doing?
 
-1. Sets up an instance of `MailosaurClient` using the `MAILOSAUR_API_KEY` environment variable.
-2. Waits for an email to arrive at the server with ID `abc123`.
+1. Sets up an instance of `MailosaurClient`, reading the API key from the `MAILOSAUR_API_KEY` environment variable.
+2. Waits for an email to arrive at the inbox (server) with ID `abc123`.
 3. Outputs the subject line of the email.
 
+### My email wasn't found
+
+First, check that the email you sent is visible in the [Mailosaur Dashboard](https://mailosaur.com/app/project/messages).
+
+If it is, the likely reason is that by default, `messages.get` only searches emails received by Mailosaur in the last 1 hour. You can override this behavior (see the `received_after` argument below), however we only recommend doing this during setup, as your tests will generally run faster with the default settings:
+
+```ruby
+require 'date'
+
+email = mailosaur.messages.get(
+  server_id,
+  criteria,
+  # Override received_after to search all messages since Jan 1st
+  received_after: DateTime.new(2021, 1, 1)
+)
+```
+
 ## 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.
@@ -122,11 +149,12 @@ If your account has [SMS testing](https://mailosaur.com/sms-testing/) enabled, y
 ```ruby
 require 'mailosaur'
 
-mailosaur = Mailosaur::MailosaurClient.new()
+mailosaur = Mailosaur::MailosaurClient.new
 
 server_id = "abc123"
+server_domain = "abc123.mailosaur.net"
 
-criteria = Mailosaur::Models::SearchCriteria.new()
+criteria = Mailosaur::Models::SearchCriteria.new
 criteria.sent_to = "4471235554444"
 
 sms = mailosaur.messages.get(server_id, criteria)
@@ -148,18 +176,15 @@ 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:
+You may have an email or SMS message that contains an account verification code, or some other one-time passcode. Mailosaur automatically extracts these for you and makes them available via the `codes` array on the message content:
 
 ```ruby
 puts(message.text.body) # "Your access code is 243546."
 
-match = message.text.body.match(/([0-9]{6})/)
-puts(match[0]) # "243546"
+puts(message.text.codes[0].value) # "243546"
 ```
 
-[Read more](https://mailosaur.com/docs/test-cases/text-content/)
+[Read more](https://mailosaur.com/docs/automation/codes)
 
 ## Testing HTML content
 
@@ -169,9 +194,9 @@ Most emails also have an HTML body, as well as the plain text content. You can a
 puts(message.html.body) # "<html><head ..."
 ```
 
-### Working with HTML using nokogiri
+### 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.
+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
@@ -182,12 +207,12 @@ require 'nokogiri'
 
 # ...
 
-@doc = Nokogiri::HTML(message.html.body)
-el = @doc.css(".verification-code")
+doc = Nokogiri::HTML(message.html.body)
+el = doc.at_css(".verification-code")
 
 verification_code = el.text
 
-puts verification_code # "542163"
+puts(verification_code) # "542163"
 ```
 
 [Read more](https://mailosaur.com/docs/test-cases/html-content/)
@@ -207,7 +232,7 @@ 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.
+**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)
 
@@ -245,6 +270,15 @@ first_attachment = message.attachments[0]
 puts(first_attachment.length) # 4028
 ```
 
+### Writing an attachment to disk
+
+```ruby
+first_attachment = message.attachments[1]
+
+file_bytes = mailosaur.files.get_attachment(first_attachment.id)
+File.binwrite(first_attachment.file_name, file_bytes)
+```
+
 ## 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:

data/lib/Mailosaur/analysis.rb

@@ -1,8 +1,11 @@
 module Mailosaur
+  # Operations for analyzing the content and deliverability of an email, including SpamAssassin
+  # scoring and per-provider deliverability reports. Accessed via +client.analysis+.
   class Analysis
     #
     # Creates and initializes a new instance of the Analysis class.
-    # @param conn client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -13,13 +16,11 @@ module Mailosaur
     attr_reader :conn
 
     #
-    # Perform a spam test
+    # Perform a spam analysis of an email.
     #
-    # Perform spam testing on the specified email
+    # @param email [String] The identifier of the message to be analyzed.
     #
-    # @param email The identifier of the email to be analyzed.
-    #
-    # @return [SpamAnalysisResult] operation results.
+    # @return [Mailosaur::Models::SpamAnalysisResult] The spam score and filter results.
     #
     def spam(email)
       response = conn.get "api/analysis/spam/#{email}"
@@ -29,13 +30,11 @@ module Mailosaur
     end
 
     #
-    # Perform a deliverability report
-    #
-    # Perform deliverability test on the specified email
+    # Perform a deliverability report of an email.
     #
-    # @param email The identifier of the email to be analyzed.
+    # @param email [String] The identifier of the message to be analyzed.
     #
-    # @return [DeliverabilityReport] operation results.
+    # @return [Mailosaur::Models::DeliverabilityReport] The deliverability report for the email.
     #
     def deliverability(email)
       response = conn.get "api/analysis/deliverability/#{email}"

data/lib/Mailosaur/devices.rb

@@ -1,8 +1,12 @@
 module Mailosaur
+  # Operations for managing virtual security devices and retrieving their current one-time
+  # passwords (OTPs), used to automate testing of app-based multi-factor authentication.
+  # Accessed via +client.devices+.
   class Devices
     #
     # Creates and initializes a new instance of the Devices class.
-    # @param client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -12,12 +16,10 @@ module Mailosaur
     # @return [Connection] the client connection.
     attr_reader :conn
 
-    #
-    # List all devices
     #
     # Returns a list of your virtual security devices.
     #
-    # @return [DeviceListResult] operation results.
+    # @return [Mailosaur::Models::DeviceListResult] Your devices.
     #
     def list
       response = conn.get 'api/devices'
@@ -27,13 +29,12 @@ module Mailosaur
     end
 
     #
-    # Create a device
-    #
-    # Creates a new virtual security device and returns it.
+    # Creates a new virtual security device.
     #
-    # @param device_create_options [DeviceCreateOptions]
+    # @param device_create_options [Mailosaur::Models::DeviceCreateOptions] Options used to
+    #   create a new Mailosaur virtual security device.
     #
-    # @return [Device] operation results.
+    # @return [Mailosaur::Models::Device] The newly-created device.
     #
     def create(device_create_options)
       response = conn.post 'api/devices', device_create_options.to_json
@@ -43,13 +44,13 @@ module Mailosaur
     end
 
     #
-    # Retrieve OTP
-    #
-    # Retrieves the current one-time password for a saved device, or given base32-encoded shared secret.
+    # Retrieves the current one-time password for a saved device, or given base32-encoded
+    # shared secret.
     #
-    # @param query [String] Either the unique identifier of the device, or a base32-encoded shared secret.
+    # @param query [String] Either the unique identifier of the device, or a base32-encoded
+    #   shared secret.
     #
-    # @return [OtpResult] operation results.
+    # @return [Mailosaur::Models::OtpResult] The current one-time password.
     #
     def otp(query)
       if query.include? '-'
@@ -68,11 +69,11 @@ module Mailosaur
     end
 
     #
-    # Delete a device
+    # Permanently delete a virtual security device. This operation cannot be undone.
     #
-    # Permanently deletes a device. This operation cannot be undone.
+    # @param id [String] The unique identifier of the device.
     #
-    # @param id [String] The identifier of the device to be deleted.
+    # @return [nil] Once the device has been deleted.
     #
     def delete(id)
       response = conn.delete "api/devices/#{id}"

data/lib/Mailosaur/files.rb

@@ -1,8 +1,11 @@
 module Mailosaur
+  # Operations for downloading the raw content associated with a message — file attachments,
+  # the full EML source of an email, and rendered email previews. Accessed via +client.files+.
   class Files
     #
     # Creates and initializes a new instance of the Files class.
-    # @param client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -13,14 +16,11 @@ module Mailosaur
     attr_reader :conn
 
     #
-    # Download an attachment
+    # Downloads a single attachment.
     #
-    # Downloads a single attachment. Simply supply the unique identifier for the
-    # required attachment.
+    # @param id [String] The identifier for the required attachment.
     #
-    # @param id The identifier of the attachment to be downloaded.
-    #
-    # @return [NOT_IMPLEMENTED] operation results.
+    # @return [String] The attachment's binary content.
     #
     def get_attachment(id)
       response = conn.get "api/files/attachments/#{id}"
@@ -29,14 +29,11 @@ module Mailosaur
     end
 
     #
-    # Download EML
-    #
-    # Downloads an EML file representing the specified email. Simply supply the
-    # unique identifier for the required email.
+    # Downloads an EML file representing the specified email.
     #
-    # @param id The identifier of the email to be downloaded.
+    # @param id [String] The identifier for the required message.
     #
-    # @return [NOT_IMPLEMENTED] operation results.
+    # @return [String] The raw EML content of the email.
     #
     def get_email(id)
       response = conn.get "api/files/email/#{id}"
@@ -44,15 +41,16 @@ module Mailosaur
       response.body
     end
 
-    #
-    # Download an email preview
     #
     # Downloads a screenshot of your email rendered in a real email client. Simply supply
     # the unique identifier for the required preview.
     #
-    # @param id The identifier of the email preview to be downloaded.
+    # @param id [String] The identifier of the email preview to be downloaded.
+    #
+    # @return [String] The preview screenshot image content.
     #
-    # @return [NOT_IMPLEMENTED] operation results.
+    # @raise [Mailosaur::MailosaurError] With error code +preview_timeout+ if the preview is
+    #   not generated within the time limit.
     #
     def get_preview(id)
       timeout = 120_000

data/lib/Mailosaur/messages.rb

@@ -1,10 +1,13 @@
 require 'uri'
 
 module Mailosaur
+  # Operations for finding, retrieving, creating, forwarding, replying to, and deleting the
+  # email and SMS messages received by your Mailosaur inboxes (servers). Accessed via +client.messages+.
   class Messages
     #
     # Creates and initializes a new instance of the Messages class.
-    # @param client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -15,22 +18,24 @@ module Mailosaur
     attr_reader :conn
 
     #
-    # Retrieve a message using search criteria
+    # Waits for a message to be found. Returns as soon as a message matching the specified
+    # search criteria is found. This is the most efficient method of looking up a message,
+    # therefore we recommend using it wherever possible.
     #
-    # Returns as soon as a message matching the specified search criteria is
-    # found. This is the most efficient method of looking up a message.
-    #
-    # @param server [String] The identifier of the server hosting the message.
-    # @param criteria [SearchCriteria] The search criteria to use in order to find
-    # a match.
+    # @param server [String] The unique identifier of the containing inbox (server).
+    # @param criteria [Mailosaur::Models::SearchCriteria] The criteria with which to find
+    #   messages during a search.
     # @param timeout [Integer] Specify how long to wait for a matching result
-    # (in milliseconds).
+    #   (in milliseconds).
     # @param received_after [DateTime] Limits results to only messages received
-    # after this date/time.
-    # @param dir [String] Optionally limits results based on the direction (`Sent`
-    # or `Received`), with the default being `Received`.
+    #   after this date/time.
+    # @param dir [String] Optionally limits results based on the direction (+Sent+
+    #   or +Received+), with the default being +Received+.
+    #
+    # @return [Mailosaur::Models::Message] The first message matching the criteria.
     #
-    # @return [Message] operation results.
+    # @raise [Mailosaur::MailosaurError] With error code +no_messages_found+ if no matching
+    #   message exists, or +search_timeout+ if no matching message arrives before the timeout elapses.
     #
     def get(server, criteria, timeout: 10_000, received_after: DateTime.now - (1.0 / 24), dir: nil)
       # Defaults timeout to 10s, receivedAfter to 1h
@@ -41,14 +46,12 @@ module Mailosaur
     end
 
     #
-    # Retrieve a message
-    #
-    # Retrieves the detail for a single email message. Simply supply the unique
-    # identifier for the required message.
+    # Retrieves the detail for a single message. Must be used in conjunction with either
+    # {#list} or {#search} in order to get the unique identifier for the required message.
     #
-    # @param id The identifier of the email message to be retrieved.
+    # @param id [String] The unique identifier of the message to be retrieved.
     #
-    # @return [Message] operation results.
+    # @return [Mailosaur::Models::Message] The full message.
     #
     def get_by_id(id)
       response = conn.get "api/messages/#{id}"
@@ -58,12 +61,12 @@ module Mailosaur
     end
 
     #
-    # Delete a message
+    # Permanently deletes a message. Also deletes any attachments related to the message.
+    # This operation cannot be undone.
     #
-    # Permanently deletes a message. This operation cannot be undone. Also deletes
-    # any attachments related to the message.
+    # @param id [String] The identifier for the message.
     #
-    # @param id The identifier of the message to be deleted.
+    # @return [nil] Once the message has been deleted.
     #
     def delete(id)
       response = conn.delete "api/messages/#{id}"
@@ -71,24 +74,22 @@ module Mailosaur
       nil
     end
 
-    #
-    # List all messages
     #
     # Returns a list of your messages in summary form. The summaries are returned
     # sorted by received date, with the most recently-received messages appearing
     # first.
     #
-    # @param server [String] The identifier of the server hosting the messages.
-    # @param page [Integer] Used in conjunction with `itemsPerPage` to support
-    # pagination.
+    # @param server [String] The unique identifier of the required inbox (server).
+    # @param page [Integer] Used in conjunction with +items_per_page+ to support
+    #   pagination.
     # @param items_per_page [Integer] A limit on the number of results to be
-    # returned per page. Can be set between 1 and 1000 items, the default is 50.
+    #   returned per page. Can be set between 1 and 1000 items, the default is 50.
     # @param received_after [DateTime] Limits results to only messages received
-    # after this date/time.
-    # @param dir [String] Optionally limits results based on the direction (`Sent`
-    # or `Received`), with the default being `Received`.
+    #   after this date/time.
+    # @param dir [String] Optionally limits results based on the direction (+Sent+
+    #   or +Received+), with the default being +Received+.
     #
-    # @return [MessageListResult] operation results.
+    # @return [Mailosaur::Models::MessageListResult] The message summaries.
     #
     def list(server, page: nil, items_per_page: nil, received_after: nil, dir: nil)
       url = "api/messages?server=#{server}"
@@ -106,12 +107,11 @@ module Mailosaur
     end
 
     #
-    # Delete all messages
+    # Permanently delete all messages within an inbox (server). This operation cannot be undone.
     #
-    # Permanently deletes all messages held by the specified server. This operation
-    # cannot be undone. Also deletes any attachments related to each message.
+    # @param server [String] The unique identifier of the inbox (server).
     #
-    # @param server [String] The identifier of the server to be emptied.
+    # @return [nil] Once all messages within the inbox (server) have been deleted.
     #
     def delete_all(server)
       response = conn.delete "api/messages?server=#{server}"
@@ -119,30 +119,31 @@ module Mailosaur
       nil
     end
 
-    #
-    # Search for messages
     #
     # Returns a list of messages matching the specified search criteria, in summary
     # form. The messages are returned sorted by received date, with the most
     # recently-received messages appearing first.
     #
-    # @param server [String] The identifier of the server hosting the messages.
-    # @param criteria [SearchCriteria] The search criteria to match results
-    # against.
-    # @param page [Integer] Used in conjunction with `itemsPerPage` to support
-    # pagination.
+    # @param server [String] The unique identifier of the inbox (server) to search.
+    # @param criteria [Mailosaur::Models::SearchCriteria] The criteria with which to find
+    #   messages during a search.
+    # @param page [Integer] Used in conjunction with +items_per_page+ to support
+    #   pagination.
     # @param items_per_page [Integer] A limit on the number of results to be
-    # returned per page. Can be set between 1 and 1000 items, the default is 50.
+    #   returned per page. Can be set between 1 and 1000 items, the default is 50.
     # @param timeout [Integer] Specify how long to wait for a matching result
-    # (in milliseconds).
+    #   (in milliseconds).
     # @param received_after [DateTime] Limits results to only messages received
-    # after this date/time.
+    #   after this date/time.
     # @param error_on_timeout [Boolean] When set to false, an error will not be
-    # throw if timeout is reached (default: true).
-    # @param dir [String] Optionally limits results based on the direction (`Sent`
-    # or `Received`), with the default being `Received`.
+    #   raised if the timeout is reached (default: true).
+    # @param dir [String] Optionally limits results based on the direction (+Sent+
+    #   or +Received+), with the default being +Received+.
     #
-    # @return [MessageListResult] operation results.
+    # @return [Mailosaur::Models::MessageListResult] The matching message summaries.
+    #
+    # @raise [Mailosaur::MailosaurError] With error code +search_timeout+ if no matching message
+    #   is found before the timeout elapses, unless +error_on_timeout+ is set to false.
     #
     def search(server, criteria, page: nil, items_per_page: nil, timeout: nil, received_after: nil, error_on_timeout: true, dir: nil)
       url = "api/messages/search?server=#{server}"
@@ -181,17 +182,16 @@ module Mailosaur
       end
     end
 
-    #
-    # Create a message.
     #
     # Creates a new message that can be sent to a verified email address. This is
     # useful in scenarios where you want an email to trigger a workflow in your
-    # product
+    # product.
     #
-    # @param server [String] The identifier of the server to create the message in.
-    # @param options [MessageCreateOptions] The options with which to create the message.
+    # @param server [String] The unique identifier of the required inbox (server).
+    # @param message_create_options [Mailosaur::Models::MessageCreateOptions] Options to use
+    #   when creating a new message.
     #
-    # @return [Message] operation result.
+    # @return [Mailosaur::Models::Message] The newly-created message.
     #
     def create(server, message_create_options)
       response = conn.post "api/messages?server=#{server}", message_create_options.to_json
@@ -201,15 +201,14 @@ module Mailosaur
     end
 
     #
-    # Forward an email.
-    #
-    # Forwards the specified email to a verified email address.
+    # Forwards the specified message to a verified email address. This is useful for
+    # simulating a user forwarding one of your email messages.
     #
-    # @param id [String] The identifier of the email to forward.
-    # @param options [MessageForwardOptions] The options with which to forward the email.
-    # against.
+    # @param id [String] The unique identifier of the message to be forwarded.
+    # @param message_forward_options [Mailosaur::Models::MessageForwardOptions] Options to use
+    #   when forwarding a message.
     #
-    # @return [Message] operation result.
+    # @return [Mailosaur::Models::Message] The forwarded message.
     #
     def forward(id, message_forward_options)
       response = conn.post "api/messages/#{id}/forward", message_forward_options.to_json
@@ -219,16 +218,14 @@ module Mailosaur
     end
 
     #
-    # Reply to an email.
+    # Sends a reply to the specified message. This is useful for when simulating a user
+    # replying to one of your email or SMS messages.
     #
-    # Sends a reply to the specified email. This is useful for when simulating a user
-    # replying to one of your emails.
+    # @param id [String] The unique identifier of the message to be replied to.
+    # @param message_reply_options [Mailosaur::Models::MessageReplyOptions] Options to use
+    #   when replying to a message.
     #
-    # @param id [String] The identifier of the email to reply to.
-    # @param options [MessageReplyOptions] The options with which to reply to the email.
-    # against.
-    #
-    # @return [Message] operation result.
+    # @return [Mailosaur::Models::Message] The reply message.
     #
     def reply(id, message_reply_options)
       response = conn.post "api/messages/#{id}/reply", message_reply_options.to_json
@@ -237,15 +234,14 @@ module Mailosaur
       Mailosaur::Models::Message.new(model)
     end
 
-    #
-    # Generate email previews.
     #
     # Generates screenshots of an email rendered in the specified email clients.
     #
     # @param id [String] The identifier of the email to preview.
-    # @param options [PreviewRequestOptions] The options with which to generate previews.
+    # @param options [Mailosaur::Models::PreviewRequestOptions] The options with which to
+    #   generate previews.
     #
-    # @return [PreviewListResult] operation result.
+    # @return [Mailosaur::Models::PreviewListResult] The generated previews.
     #
     def generate_previews(id, options)
       response = conn.post "api/messages/#{id}/screenshots", options.to_json

data/lib/Mailosaur/models/message.rb

@@ -63,7 +63,7 @@ module Mailosaur
       # @return [Metadata]
       attr_accessor :metadata
 
-      # @return [String] Identifier for the server in which the message is
+      # @return [String] Identifier for the inbox (server) in which the message is
       # located.
       attr_accessor :server
     end

data/lib/Mailosaur/models/server.rb

@@ -8,17 +8,17 @@ module Mailosaur
         @messages = data['messages']
       end
 
-      # @return [String] Unique identifier for the server. Used as username for
+      # @return [String] Unique identifier for the inbox (server). Used as username for
       # SMTP/POP3 authentication.
       attr_accessor :id
 
-      # @return [String] A name used to identify the server.
+      # @return [String] A name used to identify the inbox (server).
       attr_accessor :name
 
-      # @return Users (excluding administrators) who have access to the server.
+      # @return Users (excluding administrators) who have access to the inbox (server) when access is restricted.
       attr_accessor :users
 
-      # @return [Integer] The number of messages currently in the server.
+      # @return [Integer] The number of messages currently in the inbox (server).
       attr_accessor :messages
     end
   end

data/lib/Mailosaur/models/server_create_options.rb

@@ -5,7 +5,7 @@ module Mailosaur
         @name = data['name']
       end
 
-      # @return [String] A name used to identify the server.
+      # @return [String] A name used to identify the inbox (server).
       attr_accessor :name
     end
   end

data/lib/Mailosaur/models/server_list_result.rb

@@ -6,9 +6,9 @@ module Mailosaur
         (data['items'] || []).each do |i| @items << Mailosaur::Models::Server.new(i) end
       end
 
-      # @return [Array<Server>] The individual servers forming the result.
-      # Servers are returned sorted by creation date, with the most
-      # recently-created server appearing first.
+      # @return [Array<Server>] The individual inboxes (servers) forming the result.
+      # Inboxes (servers) are returned sorted by creation date, with the most
+      # recently-created inbox (server) appearing first.
       attr_accessor :items
     end
   end

data/lib/Mailosaur/previews.rb

@@ -1,8 +1,11 @@
 module Mailosaur
+  # Operations for discovering the email clients available for generating email previews
+  # (screenshots of an email rendered in real clients). Accessed via +client.previews+.
   class Previews
     #
     # Creates and initializes a new instance of the Previews class.
-    # @param client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -15,9 +18,7 @@ module Mailosaur
     #
     # List all email clients that can be used to generate email previews.
     #
-    # Returns a list of available email clients.
-    #
-    # @return [EmailClientListResult] operation results.
+    # @return [Mailosaur::Models::EmailClientListResult] The available email clients.
     #
     def list_email_clients
       response = conn.get 'api/screenshots/clients'

data/lib/Mailosaur/servers.rb

@@ -1,8 +1,12 @@
 module Mailosaur
+  # Operations for creating and managing your Mailosaur inboxes (servers) — they
+  # group your tests together, each with its own domain and SMTP/POP3/IMAP credentials.
+  # Accessed via +client.servers+.
   class Servers
     #
     # Creates and initializes a new instance of the Servers class.
-    # @param client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -13,12 +17,10 @@ module Mailosaur
     attr_reader :conn
 
     #
-    # List all servers
-    #
-    # Returns a list of your virtual SMTP servers. Servers are returned sorted in
+    # Returns a list of your inboxes (servers). Inboxes (servers) are returned sorted in
     # alphabetical order.
     #
-    # @return [ServerListResult] operation results.
+    # @return [Mailosaur::Models::ServerListResult] Your inboxes (servers).
     #
     def list
       response = conn.get 'api/servers'
@@ -28,13 +30,12 @@ module Mailosaur
     end
 
     #
-    # Create a server
-    #
-    # Creates a new virtual SMTP server and returns it.
+    # Creates a new inbox (server).
     #
-    # @param server_create_options [ServerCreateOptions]
+    # @param server_create_options [Mailosaur::Models::ServerCreateOptions] Options used to
+    #   create a new Mailosaur inbox (server).
     #
-    # @return [Server] operation results.
+    # @return [Mailosaur::Models::Server] The newly-created inbox (server).
     #
     def create(server_create_options)
       response = conn.post 'api/servers', server_create_options.to_json
@@ -44,14 +45,11 @@ module Mailosaur
     end
 
     #
-    # Retrieve a server
-    #
-    # Retrieves the detail for a single server. Simply supply the unique identifier
-    # for the required server.
+    # Retrieves the detail for a single inbox (server).
     #
-    # @param id [String] The identifier of the server to be retrieved.
+    # @param id [String] The unique identifier of the inbox (server).
     #
-    # @return [Server] operation results.
+    # @return [Mailosaur::Models::Server] The inbox (server).
     #
     def get(id)
       response = conn.get "api/servers/#{id}"
@@ -61,14 +59,12 @@ module Mailosaur
     end
 
     #
-    # Retrieve server password
+    # Retrieves the password for an inbox (server). This password can be used for SMTP, POP3, and
+    # IMAP connectivity.
     #
-    # 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 unique identifier of the inbox (server).
     #
-    # @param id [String] The identifier of the server.
-    #
-    # @return [String] Server password.
+    # @return [String] The password for the inbox (server).
     #
     def get_password(id)
       response = conn.get "api/servers/#{id}/password"
@@ -78,14 +74,12 @@ module Mailosaur
     end
 
     #
-    # Update a server
-    #
-    # Updats a single server and returns it.
+    # Updates the attributes of an inbox (server).
     #
-    # @param id [String] The identifier of the server to be updated.
-    # @param server [Server]
+    # @param id [String] The unique identifier of the inbox (server).
+    # @param server [Mailosaur::Models::Server] The updated inbox (server).
     #
-    # @return [Server] operation results.
+    # @return [Mailosaur::Models::Server] The updated inbox (server).
     #
     def update(id, server)
       response = conn.put "api/servers/#{id}", server.to_json
@@ -95,12 +89,12 @@ module Mailosaur
     end
 
     #
-    # Delete a server
+    # Permanently delete an inbox (server). This will also delete all messages, associated attachments,
+    # etc. within the inbox (server). This operation cannot be undone.
     #
-    # Permanently deletes a server. This operation cannot be undone. Also deletes
-    # all messages and associated attachments within the server.
+    # @param id [String] The unique identifier of the inbox (server).
     #
-    # @param id [String] The identifier of the server to be deleted.
+    # @return [nil] Once the inbox (server) has been deleted.
     #
     def delete(id)
       response = conn.delete "api/servers/#{id}"
@@ -108,6 +102,14 @@ module Mailosaur
       nil
     end
 
+    #
+    # Generates a random email address by appending a random string in front of the
+    # domain name of the inbox (server).
+    #
+    # @param server [String] The identifier of the inbox (server).
+    #
+    # @return [String] A random email address ending in the domain of the inbox (server).
+    #
     def generate_email_address(server)
       host = ENV['MAILOSAUR_SMTP_HOST'] || 'mailosaur.net'
       format('%s@%s.%s', SecureRandom.hex(3), server, host)

data/lib/Mailosaur/usage.rb

@@ -1,8 +1,11 @@
 module Mailosaur
+  # Operations for inspecting your account's usage limits and recent transactional usage.
+  # These endpoints require authentication with an account-level API key. Accessed via +client.usage+.
   class Usage
     #
     # Creates and initializes a new instance of the Usage class.
-    # @param client connection.
+    # @param conn [Faraday::Connection] The client connection.
+    # @param handle_http_error [Method] Callback used to convert HTTP error responses into errors.
     #
     def initialize(conn, handle_http_error)
       @conn = conn
@@ -13,11 +16,10 @@ module Mailosaur
     attr_reader :conn
 
     #
-    # Retrieve account usage limits.
+    # Retrieve account usage limits. Details the current limits and usage for your account.
+    # This endpoint requires authentication with an account-level API key.
     #
-    # Details the current limits and usage for your account.
-    #
-    # @return [UsageAccountLimits] operation results.
+    # @return [Mailosaur::Models::UsageAccountLimits] The usage limits for your account.
     #
     def limits
       response = conn.get 'api/usage/limits'
@@ -27,9 +29,10 @@ module Mailosaur
     end
 
     #
-    # List account transactions. Retrieves the last 31 days of transactional usage.
+    # Retrieves the last 31 days of transactional usage.
+    # This endpoint requires authentication with an account-level API key.
     #
-    # @return [UsageTransactionListResult] operation results.
+    # @return [Mailosaur::Models::UsageTransactionListResult] The transactional usage for the last 31 days.
     #
     def transactions
       response = conn.get 'api/usage/transactions'

data/lib/Mailosaur/version.rb

@@ -1,3 +1,3 @@
 module Mailosaur
-    VERSION = '8.1.0'.freeze
+    VERSION = '8.1.1'.freeze
 end

data/lib/mailosaur.rb

@@ -62,11 +62,16 @@ module Mailosaur
     autoload :BaseModel,                                          'Mailosaur/models/base_model.rb'
   end
 
+  # The Mailosaur client — the main entry point to the Mailosaur API. Construct an instance with
+  # your API key (or set the +MAILOSAUR_API_KEY+ environment variable), then use the operations
+  # namespaces (+messages+, +servers+, +files+, +devices+, +analysis+, +previews+, +usage+) to
+  # automate email and SMS testing.
   class MailosaurClient
     #
-    # Creates initializes a new instance of the MailosaurClient class.
+    # Returns an instance of the Mailosaur client.
     # @param api_key [String] Optional API key. Overrides the MAILOSAUR_API_KEY environment variable if set.
-    # @param base_url [String] the base URI of the service.
+    # @param base_url [String] Optionally overrides the base URL of the Mailosaur service.
+    # @raise [ArgumentError] If no API key is provided and the MAILOSAUR_API_KEY environment variable is not set.
     #
     def initialize(api_key = nil, base_url: 'https://mailosaur.com/')
       resolved_api_key = api_key || ENV['MAILOSAUR_API_KEY']
@@ -77,37 +82,44 @@ module Mailosaur
       @base_url = base_url
     end
 
-    # @return [Analysis] analysis
+    # Operations for analyzing email content and deliverability, including spam scoring.
+    # @return [Analysis] the analysis operations namespace.
     def analysis
       @analysis ||= Analysis.new(connection, method(:handle_http_error))
     end
 
-    # @return [Files] files
+    # Operations for downloading attachments, EML source, and email preview screenshots.
+    # @return [Files] the files operations namespace.
     def files
       @files ||= Files.new(connection, method(:handle_http_error))
     end
 
-    # @return [Messages] messages
+    # Operations for finding, retrieving, creating, and managing email and SMS messages.
+    # @return [Messages] the messages operations namespace.
     def messages
       @messages ||= Messages.new(connection, method(:handle_http_error))
     end
 
-    # @return [Servers] servers
+    # Operations for creating and managing your Mailosaur inboxes (servers).
+    # @return [Servers] the servers operations namespace.
     def servers
       @servers ||= Servers.new(connection, method(:handle_http_error))
     end
 
-    # @return [Usage] usage
+    # Operations for inspecting account usage limits and recent transactional usage.
+    # @return [Usage] the usage operations namespace.
     def usage
       @usage ||= Usage.new(connection, method(:handle_http_error))
     end
 
-    # @return [Devices] devices
+    # Operations for managing virtual security devices and retrieving their one-time passwords.
+    # @return [Devices] the devices operations namespace.
     def devices
       @devices ||= Devices.new(connection, method(:handle_http_error))
     end
 
-    # @return [Previews] previews
+    # Operations for discovering the email clients available for generating email previews.
+    # @return [Previews] the previews operations namespace.
     def previews
       @previews ||= Previews.new(connection, method(:handle_http_error))
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailosaur
 version: !ruby/object:Gem::Version
-  version: 8.1.0
+  version: 8.1.1
 platform: ruby
 authors:
 - Mailosaur
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-06 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday