mailosaur 7.3.0 → 7.3.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +273 -12
- data/lib/Mailosaur/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 9e326500621113c758df3e3d9fbc06778a9799a73e9d825de967c85c4f905d5d
|
4
|
+
data.tar.gz: f3110a0807155e33a531c655eeaeb1f05397ab501ae8a273ec6cbeff40c4adc7
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: ff7ee803eb0cc60fa0bcf7ad2f94f0103f2ebd94a056512fdb093e84f28db9cf6a00d2d6f8640fd4d439e1c120b314a05af7f37b7efda3c9ccf8b3281652caab
|
7
|
+
data.tar.gz: e807b3f423236e619b15e8cf3a4d95399531648b18f99595d31e381bc20862a7aa13286ccb686a82df99a49ff3e6934026a91d95315e1d80fba62829e7ccb5a6
|
data/README.md
CHANGED
@@ -1,30 +1,291 @@
|
|
1
|
-
# Mailosaur Ruby
|
1
|
+
# [Mailosaur - Ruby library](https://mailosaur.com/) · [![](https://github.com/mailosaur/mailosaur-ruby/workflows/CI/badge.svg)](https://github.com/mailosaur/mailosaur-ruby/actions)
|
2
2
|
|
3
|
-
|
3
|
+
Mailosaur lets you automate email and SMS tests as part of software development and QA.
|
4
4
|
|
5
|
-
|
5
|
+
- **Unlimited test email addresses for all** - every account gives users an unlimited number of test email addresses to test with.
|
6
|
+
- **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.
|
7
|
+
- **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.
|
6
8
|
|
7
|
-
##
|
9
|
+
## Get Started
|
10
|
+
|
11
|
+
This guide provides several key sections:
|
12
|
+
|
13
|
+
- [Get Started](#get-started)
|
14
|
+
- [Creating an account](#creating-an-account)
|
15
|
+
- [Test email addresses with Mailosaur](#test-email-addresses-with-mailosaur)
|
16
|
+
- [Find an email](#find-an-email)
|
17
|
+
- [Find an SMS message](#find-an-sms-message)
|
18
|
+
- [Testing plain text content](#testing-plain-text-content)
|
19
|
+
- [Testing HTML content](#testing-html-content)
|
20
|
+
- [Working with hyperlinks](#working-with-hyperlinks)
|
21
|
+
- [Working with attachments](#working-with-attachments)
|
22
|
+
- [Working with images and web beacons](#working-with-images-and-web-beacons)
|
23
|
+
- [Spam checking](#spam-checking)
|
24
|
+
|
25
|
+
You can find the full [Mailosaur documentation](https://mailosaur.com/docs/) on the website.
|
26
|
+
|
27
|
+
If you get stuck, just contact us at support@mailosaur.com.
|
28
|
+
|
29
|
+
### Installation
|
8
30
|
|
9
31
|
```
|
10
32
|
gem install mailosaur
|
11
33
|
```
|
12
34
|
|
13
|
-
|
35
|
+
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)):
|
36
|
+
|
37
|
+
```ruby
|
38
|
+
require 'mailosaur'
|
39
|
+
mailosaur = Mailosaur::MailosaurClient.new("YOUR_API_KEY")
|
40
|
+
```
|
41
|
+
|
42
|
+
### API Reference
|
43
|
+
|
44
|
+
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:
|
45
|
+
|
46
|
+
[![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)
|
47
|
+
[![Run in Insomnia}](https://insomnia.rest/images/run.svg)](https://insomnia.rest/run/?label=Mailosaur&uri=https%3A%2F%2Fmailosaur.com%2Finsomnia.json)
|
48
|
+
|
49
|
+
## Creating an account
|
50
|
+
|
51
|
+
Create a [free trial account](https://mailosaur.com/app/signup) for Mailosaur via the website.
|
52
|
+
|
53
|
+
Once you have this, navigate to the [API tab](https://mailosaur.com/app/project/api) to find the following values:
|
54
|
+
|
55
|
+
- **Server ID** - Servers act like projects, which group your tests together. You need this ID whenever you interact with a server via the API.
|
56
|
+
- **Server Domain** - Every server has its own domain name. You'll need this to send email to your server.
|
57
|
+
- **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/).
|
14
58
|
|
15
|
-
|
59
|
+
## Test email addresses with Mailosaur
|
16
60
|
|
17
|
-
|
61
|
+
Mailosaur gives you an **unlimited number of test email addresses** - with no setup or coding required!
|
18
62
|
|
19
|
-
|
63
|
+
Here's how it works:
|
64
|
+
|
65
|
+
* When you create an account, you are given a server.
|
66
|
+
* Every server has its own **Server Domain** name (e.g. `abc123.mailosaur.net`)
|
67
|
+
* Any email address that ends with `@{YOUR_SERVER_DOMAIN}` will work with Mailosaur without any special setup. For example:
|
68
|
+
* `build-423@abc123.mailosaur.net`
|
69
|
+
* `john.smith@abc123.mailosaur.net`
|
70
|
+
* `rAnDoM63423@abc123.mailosaur.net`
|
71
|
+
* You can create more servers when you need them. Each one will have its own domain name.
|
72
|
+
|
73
|
+
***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.*
|
74
|
+
|
75
|
+
## Find an email
|
76
|
+
|
77
|
+
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:
|
20
78
|
|
21
79
|
```ruby
|
22
|
-
require
|
23
|
-
|
80
|
+
require 'mailosaur'
|
81
|
+
|
82
|
+
mailosaur = Mailosaur::MailosaurClient.new("API_KEY")
|
83
|
+
|
84
|
+
# See https://mailosaur.com/app/project/api
|
85
|
+
server_id = "abc123"
|
86
|
+
server_domain = "abc123.mailosaur.net"
|
87
|
+
|
88
|
+
criteria = Mailosaur::Models::SearchCriteria.new()
|
89
|
+
criteria.sent_to = "anything@" + server_domain
|
90
|
+
|
91
|
+
email = mailosaur.messages.get(server_id, criteria)
|
92
|
+
|
93
|
+
puts(email.subject) # "Hello world!"
|
94
|
+
```
|
95
|
+
|
96
|
+
### What is this code doing?
|
97
|
+
|
98
|
+
1. Sets up an instance of `MailosaurClient` with your API key.
|
99
|
+
2. Waits for an email to arrive at the server with ID `abc123`.
|
100
|
+
3. Outputs the subject line of the email.
|
101
|
+
|
102
|
+
## Find an SMS message
|
103
|
+
|
104
|
+
**Important:** Trial accounts do not automatically have SMS access. Please contact our support team to enable a trial of SMS functionality.
|
105
|
+
|
106
|
+
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:
|
107
|
+
|
108
|
+
```ruby
|
109
|
+
require 'mailosaur'
|
110
|
+
|
111
|
+
mailosaur = Mailosaur::MailosaurClient.new("API_KEY")
|
112
|
+
|
113
|
+
server_id = "abc123"
|
114
|
+
|
115
|
+
criteria = Mailosaur::Models::SearchCriteria.new()
|
116
|
+
criteria.sent_to = "4471235554444"
|
117
|
+
|
118
|
+
sms = mailosaur.messages.get(server_id, criteria)
|
119
|
+
|
120
|
+
puts(sms.text.body)
|
121
|
+
```
|
122
|
+
|
123
|
+
## Testing plain text content
|
124
|
+
|
125
|
+
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:
|
126
|
+
|
127
|
+
```ruby
|
128
|
+
puts(message.text.body) # "Hi Jason, ..."
|
129
|
+
|
130
|
+
if message.text.body.include? "Jason"
|
131
|
+
puts("Email contains 'Jason'")
|
132
|
+
end
|
133
|
+
```
|
134
|
+
|
135
|
+
### Extracting verification codes from plain text
|
136
|
+
|
137
|
+
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.
|
138
|
+
|
139
|
+
Here is how to extract a 6-digit numeric code:
|
140
|
+
|
141
|
+
```ruby
|
142
|
+
puts(message.text.body) # "Your access code is 243546."
|
143
|
+
|
144
|
+
match = message.text.body.match(/([0-9]{6})/)
|
145
|
+
puts(match[0]) # "243546"
|
146
|
+
```
|
147
|
+
|
148
|
+
[Read more](https://mailosaur.com/docs/test-cases/text-content/)
|
149
|
+
|
150
|
+
## Testing HTML content
|
151
|
+
|
152
|
+
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:
|
153
|
+
|
154
|
+
```ruby
|
155
|
+
puts(message.html.body) # "<html><head ..."
|
156
|
+
```
|
157
|
+
|
158
|
+
### Working with HTML using nokogiri
|
159
|
+
|
160
|
+
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.
|
161
|
+
|
162
|
+
```sh
|
163
|
+
gem install nokogiri
|
164
|
+
```
|
165
|
+
|
166
|
+
```ruby
|
167
|
+
require 'nokogiri'
|
168
|
+
|
169
|
+
# ...
|
170
|
+
|
171
|
+
@doc = Nokogiri::HTML(message.html.body)
|
172
|
+
el = @doc.css(".verification-code")
|
173
|
+
|
174
|
+
verification_code = el.text
|
175
|
+
|
176
|
+
puts verification_code # "542163"
|
177
|
+
```
|
178
|
+
|
179
|
+
[Read more](https://mailosaur.com/docs/test-cases/html-content/)
|
180
|
+
|
181
|
+
## Working with hyperlinks
|
182
|
+
|
183
|
+
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.
|
184
|
+
|
185
|
+
Each link has a text property, representing the display text of the hyperlink within the body, and an href property containing the target URL:
|
186
|
+
|
187
|
+
```ruby
|
188
|
+
# How many links?
|
189
|
+
puts(message.html.links.length) # 2
|
190
|
+
|
191
|
+
first_link = message.html.links[0]
|
192
|
+
puts(first_link.text) # "Google Search"
|
193
|
+
puts(first_link.href) # "https://www.google.com/"
|
194
|
+
```
|
195
|
+
|
196
|
+
**Important:** To ensure you always have valid emails. Mailosaur only extracts links that have been correctly marked up with `<a>` or `<area>` tags.
|
197
|
+
|
198
|
+
### Links in plain text (including SMS messages)
|
199
|
+
|
200
|
+
Mailosaur auto-detects links in plain text content too, which is especially useful for SMS testing:
|
201
|
+
|
202
|
+
```ruby
|
203
|
+
# How many links?
|
204
|
+
puts(message.text.links.length) # 2
|
205
|
+
|
206
|
+
first_link = message.text.links[0]
|
207
|
+
puts(first_link.href) # "https://www.google.com/"
|
208
|
+
```
|
209
|
+
|
210
|
+
## Working with attachments
|
211
|
+
|
212
|
+
If your email includes attachments, you can access these via the `attachments` property:
|
213
|
+
|
214
|
+
```ruby
|
215
|
+
# How many attachments?
|
216
|
+
puts(message.attachments.length) # 2
|
217
|
+
```
|
218
|
+
|
219
|
+
Each attachment contains metadata on the file name and content type:
|
220
|
+
|
221
|
+
```ruby
|
222
|
+
first_attachment = message.attachments[0]
|
223
|
+
puts(first_attachment.file_name) # "contract.pdf"
|
224
|
+
puts(first_attachment.content_type) # "application/pdf"
|
225
|
+
```
|
226
|
+
|
227
|
+
The `length` property returns the size of the attached file (in bytes):
|
228
|
+
|
229
|
+
```ruby
|
230
|
+
first_attachment = message.attachments[0]
|
231
|
+
puts(first_attachment.length) # 4028
|
232
|
+
```
|
233
|
+
|
234
|
+
## Working with images and web beacons
|
235
|
+
|
236
|
+
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:
|
237
|
+
|
238
|
+
```ruby
|
239
|
+
# How many images in the email?
|
240
|
+
puts(message.html.images.length) # 1
|
241
|
+
```
|
242
|
+
|
243
|
+
### Remotely-hosted images
|
244
|
+
|
245
|
+
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.
|
246
|
+
|
247
|
+
All images should have an alternative text description, which can be checked using the `alt` attribute.
|
248
|
+
|
249
|
+
```ruby
|
250
|
+
image = message.html.images[0]
|
251
|
+
puts(image.alt) # "Hot air balloon"
|
252
|
+
```
|
253
|
+
|
254
|
+
### Triggering web beacons
|
255
|
+
|
256
|
+
A web beacon is a small image that can be used to track whether an email has been opened by a recipient.
|
257
|
+
|
258
|
+
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:
|
259
|
+
|
260
|
+
```ruby
|
261
|
+
image = message.html.images[0]
|
262
|
+
puts(image.src) # "https://example.com/s.png?abc123"
|
263
|
+
|
264
|
+
# Make an HTTP call to trigger the web beacon
|
265
|
+
uri = URI(image.src)
|
266
|
+
Net::HTTP.start(uri.host, uri.port,
|
267
|
+
:use_ssl => uri.scheme == 'https') do |http|
|
268
|
+
request = Net::HTTP::Get.new uri
|
269
|
+
|
270
|
+
response = http.request request # Net::HTTPResponse object
|
271
|
+
puts(response.code) # 200
|
272
|
+
end
|
273
|
+
```
|
274
|
+
|
275
|
+
## Spam checking
|
276
|
+
|
277
|
+
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):
|
278
|
+
|
279
|
+
```ruby
|
280
|
+
result = mailosaur.analysis.spam(message.id)
|
24
281
|
|
25
|
-
result
|
282
|
+
puts(result.score) # 0.5
|
26
283
|
|
27
|
-
|
284
|
+
for r in result.spam_filter_results.spam_assassin do
|
285
|
+
puts(r.rule)
|
286
|
+
puts(r.description)
|
287
|
+
puts(r.score)
|
288
|
+
end
|
28
289
|
```
|
29
290
|
|
30
291
|
## Development
|
data/lib/Mailosaur/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: mailosaur
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 7.3.
|
4
|
+
version: 7.3.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Mailosaur
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2021-05-
|
11
|
+
date: 2021-05-15 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: faraday
|