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.

Table of Contents

• Acknowledgments
• Installation
• Config Object
• Campaigns API
  • Create a Campaign
• Templates API
  • Get all Templates
  • Get a Specific Template
• Subscriber API
  • Create a Subscriber
  • Update a Subscriber
  • Delete a Subscriber
  • Unsubscribe a Subscriber
  • Retrieve Subscribers
  • Fetch a Subscriber by ID
  • Find a Subscriber by Email
• List API
  • Get Lists
  • Get a Specific List
  • Create a New List
  • Copy a List
  • Remove a List
  • Update a List
• Countries API
  • Get All Countries
  • Get Zones of a Country

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: "[email protected]",
		subject: "Hi!",
		replyTo: "[email protected]",
		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: "[email protected]",
	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: "[email protected]",
	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: "[email protected]"
	})
	.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: "[email protected]", //Required
		replyTo: "[email protected]", //Required
		subject: "Hi!",
		//notification when new subscriber added
		notificationSubscribe: "yes", //yes or no
		notificationUnsubscribe: "yes", //yes or no
		//where to send the notification
		notificationSubscribeTo: "[email protected]",
		notificationUnsubscribeTo: "[email protected]",
		//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: "[email protected]", //Required
        replyTo: "[email protected]", //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;
}

License

This project is licensed under the ISC License - see the LICENSE.md file for details