A NodeJS library to interact with the MailHog API
npm install mailhog> A NodeJS library to interact with the
> MailHog API.
- Installation
- Initialization
- Description
- Parameters
- Returns
- Example
- API
- messages
- Description
- Parameters
- Returns
- Example
- search
- Description
- Parameters
- Returns
- Example
- latestFrom
- Description
- Parameters
- Returns
- Example
- latestTo
- Description
- Parameters
- Returns
- Example
- latestContaining
- Description
- Parameters
- Returns
- Example
- releaseMessage
- Description
- Parameters
- Returns
- Example
- deleteMessage
- Description
- Parameters
- Returns
- Example
- deleteAll
- Description
- Parameters
- Returns
- Example
- encode
- Description
- Parameters
- Returns
- Example
- decode
- Description
- Parameters
- Returns
- Example
- Testing
- License
- Author
``sh`
npm install mailhog
``
require('mailhog')(options) → Object
The mailhog module returns an initialization function. options
This function accepts an optional object that is used formailhog
http.request
calls to the MailHog API and returns the API object.
| Name | Type | Required | Default | Description |
| ---------------- | ------ | -------- | --------- | ------------------------ |
| options.protocol | String | no | http: | API protocol |
| options.host | String | no | localhost | API host |
| options.port | Number | no | 8025 | API port |
| options.auth | String | no | | API basic authentication |
| options.basePath | String | no | /api | API base path |
Returns the mailhog API object with the following properties:
`js`
{
options: Object,
messages: Function,
search: Function,
latestFrom: Function,
latestTo: Function,
latestContaining: Function,
releaseMessage: Function,
deleteMessage: Function,
deleteAll: Function,
encode: Function,
decode: Function
}
`js
const mailhog = require('mailhog')({
host: 'mailhog'
})
mailhog.messages().then(result => console.log(result))
`
The following API descriptions assume that the mailhog API object has been
initialized.
``
mailhog.messages(start, limit) → Promise
#### Description
Retrieves a list of mail objects, sorted from latest to earliest.
#### Parameters
| Name | Type | Required | Default | Description |
| ----- | ------ | -------- | ------- | --------------------------------- |
| start | Number | no | 0 | defines the messages query offset |
| limit | Number | no | 50 | defines the max number of results |
#### Returns
Returns a Promise that resolves with an Object.
The resolved result has the following properties:
`js`
{
total: Number, // Number of results available
count: Number, // Number of results returned
start: Number, // Offset for the range of results returned
items: Array // List of mail object items
}
The individual mail object items have the following properties:
`js`
{
ID: String, // Mail ID
text: String, // Decoded mail text content
html: String, // Decoded mail HTML content
subject: String, // Decoded mail Subject header
from: String, // Decoded mail From header
to: String, // Decoded mail To header
cc: String, // Decoded mail Cc header
bcc: String, // Decoded mail Bcc header
replyTo: String, // Decoded mail Reply-To header
date: Date, // Mail Date header
deliveryDate: Date, // Mail Delivery-Date header
attachments: Array // List of mail attachments
}
The individual attachments have the following properties:
`js`
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
#### Example
`js
async function example() {
// Retrieve the latest 10 messages:
const result = await mailhog.messages(0, 10)
// Log the details of each message to the console:
for (let item of result.items) {
console.log('From: ', item.from)
console.log('To: ', item.to)
console.log('Subject: ', item.subject)
console.log('Content: ', item.text)
}
}
`
``
mailhog.search(query, kind, start, limit) → Promise
#### Description
Retrieves a list of mail objects for the given query, sorted from latest to
earliest.
#### Parameters
| Name | Type | Required | Default | Description |
| ----- | ------ | -------- | ---------- | --------------------------------- |
| query | String | yes | | search query |
| kind | String | no | containing | query kind (from/to/containing) |
| start | Number | no | 0 | defines the search query offset |
| limit | Number | no | 50 | defines the max number of results |
#### Returns
Returns a Promise that resolves with an Object.
The resolved result has the following properties:
`js`
{
total: Number, // Number of results available
count: Number, // Number of results returned
start: Number, // Offset for the range of results returned
items: Array // List of mail object items
}
The individual mail object items have the following properties:
`js`
{
ID: String, // Mail ID
text: String, // Decoded mail text content
html: String, // Decoded mail HTML content
subject: String, // Decoded mail Subject header
from: String, // Decoded mail From header
to: String, // Decoded mail To header
cc: String, // Decoded mail Cc header
bcc: String, // Decoded mail Bcc header
replyTo: String, // Decoded mail Reply-To header
date: Date, // Mail Date header
deliveryDate: Date, // Mail Delivery-Date header
attachments: Array // List of mail attachments
}
The individual attachments have the following properties:
`js`
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
#### Example
`js
async function example() {
// Search the latest 10 messages containing "banana":
const result = await mailhog.search('banana', 'containing', 0, 10)
// Log the details of each message to the console:
for (let item of result.items) {
console.log('From: ', item.from)
console.log('To: ', item.to)
console.log('Subject: ', item.subject)
console.log('Content: ', item.text)
}
}
`
``
mailhog.latestFrom(query) → Promise
#### Description
Retrieves the latest mail object sent from the given address.
#### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ------------ |
| query | String | yes | from address |
#### Returns
Returns a Promise that resolves with an Object.
The resolved mail object has the following properties:
`js`
{
ID: String, // Mail ID
text: String, // Decoded mail text content
html: String, // Decoded mail HTML content
subject: String, // Decoded mail Subject header
from: String, // Decoded mail From header
to: String, // Decoded mail To header
cc: String, // Decoded mail Cc header
bcc: String, // Decoded mail Bcc header
replyTo: String, // Decoded mail Reply-To header
date: Date, // Mail Date header
deliveryDate: Date, // Mail Delivery-Date header
attachments: Array // List of mail attachments
}
The individual attachments have the following properties:
`js`
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
#### Example
`js
async function example() {
// Search the latest message from "test@example.org":
const result = await mailhog.latestFrom('test@example.org')
// Log the details of this message to the console:
console.log('From: ', result.from)
console.log('To: ', result.to)
console.log('Subject: ', result.subject)
console.log('Content: ', result.text)
}
`
``
mailhog.latestTo(query) → Promise
#### Description
Retrieves the latest mail object sent to the given address.
#### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ----------- |
| query | String | yes | to address |
#### Returns
Returns a Promise that resolves with an Object.
The resolved mail object has the following properties:
`js`
{
ID: String, // Mail ID
text: String, // Decoded mail text content
html: String, // Decoded mail HTML content
subject: String, // Decoded mail Subject header
from: String, // Decoded mail From header
to: String, // Decoded mail To header
cc: String, // Decoded mail Cc header
bcc: String, // Decoded mail Bcc header
replyTo: String, // Decoded mail Reply-To header
date: Date, // Mail Date header
deliveryDate: Date, // Mail Delivery-Date header
attachments: Array // List of mail attachments
}
The individual attachments have the following properties:
`js`
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
#### Example
`js
async function example() {
// Search the latest message to "test@example.org":
const result = await mailhog.latestTo('test@example.org')
// Log the details of this message to the console:
console.log('From: ', result.from)
console.log('To: ', result.to)
console.log('Subject: ', result.subject)
console.log('Content: ', result.text)
}
`
``
mailhog.latestContaining(query) → Promise
#### Description
Retrieves the latest mail object containing the given query.
#### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ------------ |
| query | String | yes | search query |
#### Returns
Returns a Promise that resolves with an Object.
The resolved mail object has the following properties:
`js`
{
ID: String, // Mail ID
text: String, // Decoded mail text content
html: String, // Decoded mail HTML content
subject: String, // Decoded mail Subject header
from: String, // Decoded mail From header
to: String, // Decoded mail To header
cc: String, // Decoded mail Cc header
bcc: String, // Decoded mail Bcc header
replyTo: String, // Decoded mail Reply-To header
date: Date, // Mail Date header
deliveryDate: Date, // Mail Delivery-Date header
attachments: Array // List of mail attachments
}
The individual attachments have the following properties:
`js`
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
#### Example
`js
async function example() {
// Search the latest message containing "banana":
const result = await mailhog.latestContaining('banana')
// Log the details of this message to the console:
console.log('From: ', result.from)
console.log('To: ', result.to)
console.log('Subject: ', result.subject)
console.log('Content: ', result.text)
}
`
``
mailhog.releaseMessage(id, config) → Promise
#### Description
Releases the mail with the given ID using the provided SMTP config.
#### Parameters
| Name | Type | Required | Description |
| ---------------- | ------ | -------- | ---------------------------------- |
| id | String | yes | message ID |
| config | Object | yes | SMTP configuration |
| config.host | String | yes | SMTP host |
| config.port | String | yes | SMTP port |
| config.email | String | yes | recipient email |
| config.username | String | no | SMTP username |
| config.password | String | no | SMTP password |
| config.mechanism | String | no | SMTP auth type (PLAIN or CRAM-MD5) |
#### Returns
Returns a Promise that resolves with an
http.IncomingMessage
object.
#### Example
`js
async function example() {
const result = await mailhog.latestTo('test@example.org')
const response = await mailhog.releaseMessage(result.ID, {
host: 'localhost',
port: '1025',
email: 'test@example.org'
})
}
`
``
mailhog.deleteMessage(id) → Promise
#### Description
Deletes the mail with the given ID from MailHog.
#### Parameters
| Name | Type | Required | Description |
| ---- | ------ | -------- | ----------- |
| id | String | yes | message ID |
#### Returns
Returns a Promise that resolves with an
http.IncomingMessage
object.
#### Example
`js
async function example() {
const result = await mailhog.latestTo('test@example.org')
const response = await mailhog.deleteMessage(result.ID)
console.log('Status code: ', response.statusCode)
}
`
``
mailhog.deleteAll() → Promise
#### Description
Deletes all mails stored in MailHog.
#### Parameters
None
#### Returns
Returns a Promise that resolves with an
http.IncomingMessage
object.
#### Example
`js
async function example() {
const response = await mailhog.deleteAll()
console.log('Status code: ', response.statusCode)
}
`
``
mailhog.encode(str, encoding, charset, lineLength) → String
#### Description
Encodes a String in the given charset to base64 or quoted-printable encoding.
#### Parameters
| Name | Type | Required | Default | Description |
| ---------- | ------ | -------- | ------- | --------------------------- |
| str | String | yes | | String to encode |
| encoding | String | yes | utf8 | base64/quoted-printable |
| charset | String | no | utf8 | Charset of the input string |
| lineLength | Number | no | 76 | Soft line break limit |
#### Returns
Returns a String in the target encoding.
#### Example
`js
const query = mailhog.encode('üäö', 'quoted-printable')
// =C3=BC=C3=A4=C3=B6
async function example() {
// Search for "üäö" in quoted-printable encoding:
const result = await mailhog.search(query)
}
`
``
mailhog.decode(str, encoding, charset) → String
#### Description
Decodes a String from the given encoding and outputs it in the given charset.
#### Parameters
| Name | Type | Required | Default | Description |
| -------- | ------ | -------- | ------- | ----------------------------- |
| str | String | yes | | String to decode |
| encoding | String | yes | | base64/quoted-printable |
| charset | String | no | utf8 | Charset to use for the output |
#### Returns
Returns a String in the target charset.
#### Example
`js`
const output = mailhog.decode('5pel5pys', 'base64')
// 日本
1. Start Docker.
2. Install development dependencies:
`sh`
npm install
`
3. Run the tests:
sh``
npm test
Released under the MIT license.