mailhog

> A NodeJS library to interact with the
> MailHog API.

Contents

- 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

Installation

``sh
npm install mailhog
`

Initialization

`
require('mailhog')(options) → Object
`

$3

The mailhog module returns an initialization function.
This function accepts an optional options object that is used for
http.request
calls to the MailHog API and returns the mailhog API object.

$3

| 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 |

$3

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
}
`

$3

`js
const mailhog = require('mailhog')({
host: 'mailhog'
})

mailhog.messages().then(result => console.log(result))
`

API

The following API descriptions assume that the mailhog API object has been
initialized.

$3

`
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)
}
}
`

$3

`
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)
}
}
`

$3

`
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)
}
`

$3

`
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)
}
`

$3

`
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)
}
`

$3

`
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'
})
}
`

$3

`
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)
}
`

$3

`
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)
}
`

$3

`
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)
}
`

$3

`
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')
// 日本
`

Testing

1. Start Docker.
2. Install development dependencies:
`sh
npm install
`
3. Run the tests:
`sh
npm test
``

License

Released under the MIT license.

Author

Sebastian Tschan