A NodeJS library to interact with the MailHog API.
npm install mailhog
require('mailhog')(options) → Object
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.
| 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:
{
options: Object,
messages: Function,
search: Function,
latestFrom: Function,
latestTo: Function,
latestContaining: Function,
releaseMessage: Function,
deleteMessage: Function,
deleteAll: Function,
encode: Function,
decode: Function
}
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
Retrieves a list of mail objects, sorted from latest to earliest.
| 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 a Promise that resolves with an Object.
The resolved result has the following properties:
{
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:
{
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:
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
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
Retrieves a list of mail objects for the given query, sorted from latest to earliest.
| 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 a Promise that resolves with an Object.
The resolved result has the following properties:
{
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:
{
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:
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
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
Retrieves the latest mail object sent from the given address.
| Name | Type | Required | Description |
|---|---|---|---|
| query | String | yes | from address |
Returns a Promise that resolves with an Object.
The resolved mail object has the following properties:
{
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:
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
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
Retrieves the latest mail object sent to the given address.
| Name | Type | Required | Description |
|---|---|---|---|
| query | String | yes | to address |
Returns a Promise that resolves with an Object.
The resolved mail object has the following properties:
{
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:
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
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
Retrieves the latest mail object containing the given query.
| Name | Type | Required | Description |
|---|---|---|---|
| query | String | yes | search query |
Returns a Promise that resolves with an Object.
The resolved mail object has the following properties:
{
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:
{
name: String, // Filename
type: String, // Content-Type
encoding: String, // Content-Transfer-Encoding
Body: String // Encoded content
}
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
Releases the mail with the given ID using the provided SMTP config.
| 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 a Promise that resolves with an
http.IncomingMessage
object.
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
Deletes the mail with the given ID from MailHog.
| Name | Type | Required | Description |
|---|---|---|---|
| id | String | yes | message ID |
Returns a Promise that resolves with an
http.IncomingMessage
object.
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
Deletes all mails stored in MailHog.
None
Returns a Promise that resolves with an
http.IncomingMessage
object.
async function example() {
const response = await mailhog.deleteAll()
console.log('Status code: ', response.statusCode)
}
mailhog.encode(str, encoding, charset, lineLength) → String
Encodes a String in the given charset to base64 or quoted-printable encoding.
| 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 a String in the target encoding.
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
Decodes a String from the given encoding and outputs it in the given charset.
| 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 a String in the target charset.
const output = mailhog.decode('5pel5pys', 'base64')
// 日本
npm install
npm test
Released under the MIT license.
FAQs
A NodeJS library to interact with the MailHog API
We found that mailhog demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.