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

Click to expand

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

Click to expand

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

Response (Click to expand)

CreateCampaignResponse {
	status: string;
	campaign_uid: string;
}

Templates API

Click to expand

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

Response (Click to expand)

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

Response (Click to expand)

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

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

Subscriber API

Click to expand

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

EmailSearchResponse {
	status: string;
	data: EmailSearchResponseData;
}

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

List API

Click to expand

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

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

Response (Click to expand)

UpdateListResponse {
	status: string;
}

Countries API

Click to expand

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

Response (Click to expand)

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

Response (Click to expand)

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Node.JS Integration for Mailwizz

Acknowledgments

Getting Started

Installation

Table of Contents

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

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Node.JS Integration for Mailwizz

Acknowledgments

Getting Started

Installation

Table of Contents

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

License