Node-mailwizz NPM

Node.JS Integration for Mailwizz

Harness the power of MailWizz, the full-featured, self-hosted email marketing software that's been battle-tested since 2013. With top-notch support, extensive documentation, and a developer-friendly environment, MailWizz integrates seamlessly with a plethora of third-party services like Sendgrid, Amazon SES, and Mailgun.

🔗 MailWizz Official Website

Acknowledgments

A huge shoutout to the brilliant minds behind the evolution of this library:

ntlzz93: For crafting the original library that started it all.
chgonzalez9: For helping with the migration to TypeScript, enhancing the developer experience.
kodjunkie: For contributing the unsubscribe method, a crucial feature for email marketing.

Your contributions have been instrumental in shaping node-mailwizz into the tool it is today!

Getting Started

Installation

Install node-mailwizz via npm to jumpstart your email marketing campaigns:

npm install node-mailwizz --save

🔥 Got an idea or facing an issue? Jump right in with a pull request or spark a discussion with an issue.

📂 For a sneak peek at the available APIs and their parameters, take a dive into the src directory, some of them are available but not documented yet.

Config Object

The config object is required to initialize the API classes. It contains the following properties:

const config = {
	publicKey: "yourPublicKey",
	secret: "yourSecretKey",
	baseUrl: "yourMailwizzApiUrl"
};

Campaigns API

Create a Campaign

import { Campaigns, CreateCampaignType } from "node-mailwizz";

const campaigns = new Campaigns(config);

campaigns
	.create({
		name: "Campaign Name",
		type: CreateCampaignType.REGULAR,
		fromName: "Mikel Calvo",
		fromEmail: "spam@mikelcalvo.net",
		subject: "Hi!",
		replyTo: "spam@mikecalvo.net",
		sendAt: "2021-01-01 00:00:00",
		listId: "YOUR-LIST-ID",
		segmentId: "YOUR-SEGMENT-ID",
		urlTracking: "yes",
		templateId: "YOUR-TEMPLATE-ID"
	})
	.then(result => console.log("Campaign created:", result))
	.catch(err => console.error("Error:", err));

CreateCampaignResponse {
	status: string;
	campaign_uid: string;
}

Templates API

Get all Templates

import { Templates } from "node-mailwizz";

const templates = new Templates(config);

templates
	.getAll({
		page: 1,
		per_page: 10
	})
	.then(result => console.log("Templates:", result))
	.catch(err => console.error("Error:", err));

GetAllTemplatesResponse {
	status: string;
	data: {
		records: GetAllTemplatesResponseRecord[];
	};
}

GetAllTemplatesResponseRecord {
	template_uid: string;
	name: string;
	screenshot: string;
}

Get a Specific Template

import { Templates } from "node-mailwizz";

const templates = new Templates(config);

templates
	.getTemplate({
		templateID: "YOUR-TEMPLATE-ID"
	})
	.then(result => console.log("Template details:", result))
	.catch(err => console.error("Error:", err));

GetTemplateResponse {
	status: string;
	data: {
		record: GetTemplateResponseRecord;
	};
}

GetTemplateResponseRecord {
    template_uid: string;
    name: string;
    screenshot: string;
}

Subscriber API

Create a Subscriber

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);

let userInfo: CreateSubscriberParamsData = {
	//Replace the values with your user info
	email: "spam@mikelcalvo.net",
	FNAME: "Mikel",
	LNAME: "Calvo",
	CUSTOM: "yourCustomField"
};

subscribers
	.create({
        listUid: "YOUR-LIST-ID",
        data: userInfo,
    })
	.then(result => console.log("Subscriber created:", result))
	.catch(err => console.error("Error:", err));

CreateSubscriberResponse {
	status: string;
	data: CreateSubscriberResponseData;
}

CreateSubscriberResponseData {
	record: CreateSubscriberResponseRecord;
}

CreateSubscriberResponseRecord {
	subscriber_uid: string;
	email: string;
	ip_address: string;
	source: string;
	date_added: CreateSubscriberResponseRecordDateAdded;
}

CreateSubscriberResponseRecordDateAdded {
	expression: string;
	params: any;
}

Update a Subscriber

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);
// Similar to creating a subscriber, but with updated info

let updatedUserInfo: UpdateSubscriberParamsData = {
	//Replace the values with your user info
	EMAIL: "spam@mikelcalvo.net",
	FNAME: "Mikel",
	LNAME: "Calvo",
	CUSTOM: "yourCustomField"
};

subscribers
	.update({
        listUid: "YOUR-LIST-ID",
        subscriberUid: "SUBSCRIBER-ID",
        data: updatedUserInfo,
    })
	.then(result => console.log("Subscriber updated:", result))
	.catch(err => console.error("Error:", err));

UpdateSubscriberResponse {
	status: string;
	data: UpdateSubscriberResponseData;
}

UpdateSubscriberResponseData {
    record: UpdateSubscriberResponseRecord;
}

UpdateSubscriberResponseRecord {
    subscriber_uid: string;
    email: string;
    ip_address: string;
    source: string;
    date_added: UpdateSubscriberResponseRecordDateAdded;
}

UpdateSubscriberResponseRecordDateAdded {
    expression: string;
    params: any;
}

Delete a Subscriber

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);

subscribers
	.delete({
		listUid: "YOUR-LIST-ID",
		subscriberUid: "SUBSCRIBER-ID"
	})
	.then(result => console.log("Subscriber deleted:", result))
	.catch(err => console.error("Error:", err));

DeleteSubscriberResponse {
	status: string;
}

Unsubscribe a Subscriber

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);

subscribers
	.unsubscribe({
		listUid: "YOUR-LIST-ID",
		subscriberUid: "SUBSCRIBER-ID"
	})
	.then(result => console.log("Subscriber unsubscribed:", result))
	.catch(err => console.error("Error:", err));

UnsubscribeSubscriberResponse {
    status: string;
}

Retrieve Subscribers

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);
// Get a paginated list of subscribers
subscribers
	.getSubscribers({
		listUid: "YOUR-LIST-ID",
		page: 1,
		per_page: 10
	})
	.then(result => console.log("Subscribers:", result))
	.catch(err => console.error("Error:", err));

GetSubscribersResponse {
	status: string;
	data: {
		count: string;
		total_pages: number;
		current_page: number;
		next_page: number;
		prev_page: number;
		records: GetSubscribersResponseRecord[];
	};
}

GetSubscribersResponseRecord {
	subscriber_uid: string;
	EMAIL: string;
	FNAME: string;
	LNAME: string;
	status: string;
	source: string;
	ip_address: string;
	date_added: string;
    [key: string]: any;
}

Fetch a Subscriber by ID

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);

subscribers
	.getSubscriber({
		listUid: "YOUR-LIST-ID",
		subscriberUid: "SUBSCRIBER-ID"
	})
	.then(result => console.log("Subscriber details:", result))
	.catch(err => console.error("Error:", err));

GetSubscriberResponse {
	status: string;
	data: GetSubscriberResponseData;
}

GetSubscriberResponseData {
	subscriber_uid: string;
	EMAIL: string;
	FNAME: string;
	LNAME: string;
	status: string;
	source: string;
	ip_address: string;
	date_added: string;
	[key: string]: any;
}

Find a Subscriber by Email

import { ListSubscribers } from "node-mailwizz";

const subscribers = new ListSubscribers(config);

subscribers
	.emailSearch({
		listUid: "YOUR-LIST-ID",
		email: "spam@mikelcalvo.net"
	})
	.then(result => console.log("Subscriber found:", result))
	.catch(err => console.error("Error:", err));

EmailSearchResponse {
	status: string;
	data: EmailSearchResponseData;
}

EmailSearchResponseData {
	subscriber_uid: string;
	status: string;
	date_added: string;
}

List API

Get Lists

import { Lists } from "node-mailwizz";

const lists = new Lists(config);

// Retrieve your lists with pagination
lists
	.getLists({
		page: 1,
		per_page: 10
	})
	.then(result => console.log("Lists:", result))
	.catch(err => console.error("Error:", err));

GetAllListsResponse {
	status: string;
	data: {
		count: string;
		total_pages: number;
		current_page: number;
		next_page: number;
		prev_page: number;
		records: GetAllListsResponseRecord[];
	};
}

GetAllListsResponseRecord {
	general: GetAllListsResponseRecordGeneral;
	defaults: GetAllListsResponseRecordDefaults;
	notifications: GetAllListsResponseRecordNotifications;
	company: GetAllListsResponseRecordCompany;
}

GetAllListsResponseRecordGeneral {
	list_uid: string;
	name: string;
	display_name: string;
	description: string;
}

GetAllListsResponseRecordDefaults {
	from_name: string;
	reply_to: string;
	subject: string;
}

GetAllListsResponseRecordNotifications {
	subscribe: string;
	unsubscribe: string;
	subscribe_to: string;
	unsubscribe_to: string;
}

GetAllListsResponseRecordCompany {
	name: string;
	address_1: string;
	address_2: string;
	zone_name: string;
	city: string;
	zip_code: string;
	phone: string;
	address_format: string;
	country: GetAllListsResponseRecordCompanyCountry;
}

GetAllListsResponseRecordCompanyCountry {
	country_id: string;
	name: string;
	code: string;
}

Get a Specific List

import { Lists } from "node-mailwizz";

const lists = new Lists(config);

lists
	.getList({
		listID: "YOUR-LIST-ID"
	})
	.then(result => console.log("List details:", result))
	.catch(err => console.error("Error:", err));

GetListResponse {
	status: string;
	data: {
		record: GetListResponseRecord;
	};
}

GetListResponseRecord {
	general: GetListResponseRecordGeneral;
	defaults: GetListResponseRecordDefaults;
	notifications: GetListResponseRecordNotifications;
	company: GetListResponseRecordCompany;
}

GetListResponseRecordGeneral {
	list_uid: string;
	name: string;
	display_name: string;
	description: string;
}

GetListResponseRecordDefaults {
	from_name: string;
	reply_to: string;
	subject: string;
}

GetListResponseRecordNotifications {
	subscribe: string;
	unsubscribe: string;
	subscribe_to: string;
	unsubscribe_to: string;
}

GetListResponseRecordCompany {
	name: string;
	address_1: string;
	address_2: string;
	zone_name: string;
	city: string;
	zip_code: string;
	phone: string;
	address_format: string;
	country: GetListResponseRecordCompanyCountry;
}

GetListResponseRecordCompanyCountry {
	country_id: string;
	name: string;
	code: string;
}

Create a New List

import { Lists } from "node-mailwizz";

const lists = new Lists(config);

lists
	.create({
		//Replace the values with your list info
		name: "Main List", //Required
		description: "This is a test list", //Required
		fromName: "Mikel Calvo", //Required
		fromEmail: "spam@mikelcalvo.net", //Required
		replyTo: "spam@mikelcalvo.net", //Required
		subject: "Hi!",
		//notification when new subscriber added
		notificationSubscribe: "yes", //yes or no
		notificationUnsubscribe: "yes", //yes or no
		//where to send the notification
		notificationSubscribeTo: "spam@mikelcalvo.net",
		notificationUnsubscribeTo: "spam@mikelcalvo.net",
		//This is optional, if not set customer company data will be used:
		companyName: "Mikel Calvo SL", //required
		companyCountry: "Spain", //required
		companyZone: "Basque Country", //required
		companyAddress1: "Some street address", //required
		companyAddress2: "",
		companyZoneName: "", //when country doesn't have required zone
		companyCity: "",
		companyZipCode: ""
	})
	.then(result => console.log("List created:", result))
	.catch(err => console.error("Error:", err));

CreateListResponse {
	status: string;
	list_uid: string;
}

Copy a List

import { Lists } from "node-mailwizz";

const lists = new Lists(config);

lists
	.copy({
		listID: "YOUR-LIST-ID"
	})
	.then(result => console.log("List copied:", result))
	.catch(err => console.error("Error:", err));

CopyListResponse {
    status: string;
    list_uid: string;
}

Remove a List

import { Lists } from "node-mailwizz";

const lists = new Lists(config);

lists
	.delete({
		listID: "YOUR-LIST-ID"
	})
	.then(result => console.log("List removed:", result))
	.catch(err => console.error("Error:", err));

DeleteListResponse {
	status: string;
}

Update a List

// Similar to creating a list, but with updated info
import { Lists } from "node-mailwizz";

const lists = new Lists(config);

lists
	.update({
        listID: "YOUR-LIST-ID",
        name: "Main List", //Required
        description: "This is a test list", //Required
        fromName: "Mikel Calvo", //Required
        fromEmail: "spam@mikelcalvo.net", //Required
        replyTo: "spam@mikelcalvo.net", //Required
        subject: "Hi!",
        //notification when new subscriber added
        notificationSubscribe: "yes", //yes or no
        notificationUnsubscribe: "yes", //yes or no
        //where to send the notification
        notificationSubscribeTo: "
        notificationUnsubscribeTo: "
        //This is optional, if not set customer company data will be used:
        companyName: "Mikel Calvo SL", //required
        companyCountry: "Spain", //required
        companyZone: "Basque Country", //required
        companyAddress1: "Some street address", //required
        companyAddress2: "",
        companyZoneName: "", //when country doesn't have required zone
        companyCity: "",
        companyZipCode: ""
    })
	.then(result => console.log("List updated:", result))
	.catch(err => console.error("Error:", err));

UpdateListResponse {
	status: string;
}

Countries API

Get All Countries

import { Countries } from "node-mailwizz";

const countriesClass = new Countries(config);

countriesClass
	.getAll({
		page: 1,
		per_page: 10
	})
	.then(countries => console.log("Countries:", countries))
	.catch(err => console.error("Error:", err));

GetAllCountriesResponse {
	status: string;
	data: {
		count: string;
		total_pages: number;
		current_page: number;
		next_page: number;
		prev_page: number;
		records: GetAllCountriesResponseRecord[];
	};
}

GetAllCountriesResponseRecord {
	country_id: string;
	name: string;
	code: string;
}

Get Zones of a Country

import { Countries } from "node-mailwizz";

const countriesClass = new Countries(config);

countriesClass
	.getAllZones({
		countryID: "ES",
		page: 1,
		per_page: 10
	})
	.then(zones => console.log("Zones:", zones))
	.catch(err => console.error("Error:", err));

GetAllZonesResponse {
	status: string;
	data: {
		count: string;
		total_pages: number;
		current_page: number;
		next_page: number;
		prev_page: number;
		records: GetAllZonesResponseRecord[];
	};
}

GetAllZonesResponseRecord {
    zone_id: string;
    name: string;
    code: string;
}