cloudmailin

CloudMailin Node.js Library

A Node.JS SDK for CloudMailin written in Typescript for receiving incoming email via JSON HTTP POST.

Please see the Documentation for more details and examples.

Usage

You can install the library using NPM.

npm install cloudmailin

Receiving Email

We recommend you take a look at our Documentation for a more detailed example but here's a snippet:

import express from "express";
import bodyParser from "body-parser";
import { IncomingMail } from "cloudmailin";

const app = express();
app.use(bodyParser.json());

app.post("/incoming_mails/", (req, res) => {
  const mail = <IncomingMail>req.body;

  res.status(201).json(mail);
}

Sending Email

You can initialize the MessageClient in two ways:

Using explicit credentials

import { MessageClient } from "cloudmailin"

const client = new MessageClient({
  username: "your-username",
  apiKey: "your-api-key"
});
const response = await client.sendMessage({
  to: '[e-mail]',
  from: '[e-mail]',
  plain: 'test message',
  html:  '<h1>Test Message</h1>',
  subject: "hello world"
});

Using SMTP URL (options or environment variable)

You can provide the SMTP URL either as an option or via environment variable:

Option 1: Pass smtpUrl directly

import { MessageClient } from "cloudmailin"

const client = new MessageClient({
  smtpUrl: "smtp://username:[e-mail]:587?starttls=true"
});
const response = await client.sendMessage({
  to: '[e-mail]',
  from: '[e-mail]',
  plain: 'test message',
  html:  '<h1>Test Message</h1>',
  subject: "hello world"
});

Option 2: Use environment variable

export CLOUDMAILIN_SMTP_URL="smtp://username:[e-mail]:587?starttls=true"

import { MessageClient } from "cloudmailin"

const client = new MessageClient(); // Will automatically use CLOUDMAILIN_SMTP_URL
const response = await client.sendMessage({
  to: '[e-mail]',
  from: '[e-mail]',
  plain: 'test message',
  html:  '<h1>Test Message</h1>',
  subject: "hello world"
});

Note: The SMTP URL format is smtp://username:apikey@host:port?params. The host and port in the URL are not used for the API calls - the library automatically uses the correct CloudMailin API endpoint at https://api.cloudmailin.com/api/v0.1/{username}/messages.

Development

Generating the OpenAPI reference:

npx openapi-typescript ./path_to/api.yaml --output ./src/models/cloudmailin-api.ts

Changelog

[0.2.0] - 2025-09-16

Added

• Support for initializing MessageClient using CLOUDMAILIN_SMTP_URL environment variable
• Support for passing smtpUrl directly as an option in MessageClientOptions

Changed

• MessageClient constructor signature simplified to accept MessageClientOptions (where all fields are now optional)