Description

n8n-nodes-mailgraf

This is an n8n community node. It lets you use MailGraf in your n8n workflows.

MailGraf is an email marketing platform for newsletters, campaigns and automations. This package adds two nodes: MailGraf (actions) and MailGraf Trigger (instant webhooks).

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
MailGraf Trigger
Credentials
Compatibility
Usage
Resources
Version history

Installation

Follow the installation guide in the n8n community nodes documentation. The package name is n8n-nodes-mailgraf.

Operations

Contact

• Create or Update: creates a contact, or updates the contact with the same email address. Optional first name, last name, country, custom fields, tags and list. Switch on Double Opt-In to send a confirmation email instead; MailGraf creates the contact (and adds the list) only after the link is clicked.
• Get: by email address or contact ID.
• Get Many: newest first, with cursor pagination handled for you. Filter by Tag or by Updated Since to get only the contacts whose details, status or email engagement changed, the base of a daily CRM sync. Every contact carries its temperature (new, hot, cooling, cold), engagement stars (0 to 5), last email open or click, tags and lists.
• Add to List: adds a contact to a list, creating the contact if it does not exist.
• Remove From List: removes the membership; the contact stays in the account.
• Add Tags: adds tags by name; tags that do not exist yet are created. A new tag can start a MailGraf automation whose trigger is “Contact receives a tag”.
• Remove Tag: removes a tag from a contact; the tag stays in the account.
• Unsubscribe: sets the contact to unsubscribed. There is no way back to active through the API; the contact has to opt in again.
• Block: adds an email address to the account block list.

Event

• Send: records a custom event (for example order_paid) for an existing contact. An automation in MailGraf can start on that event. Optional properties (JSON, up to 8 KB), timestamp within the last 24 hours, and a deduplication key that makes retries safe.

List

• Get Many: lists with their IDs.

Campaign

• Get Many: campaigns, newest first.
• Get Report: recipients, deliveries, opens, clicks, bounces, complaints and unsubscribes for one campaign.

Custom Field

• Get Many: the custom fields defined in the account, with their keys, types and options.

MailGraf Trigger

The trigger registers a webhook in MailGraf when the workflow is activated and removes it when the workflow is deactivated. MailGraf posts each event the moment it happens. Events:

• Contact Confirmed (double opt-in)
• Contact Unsubscribed
• Email Bounced
• Contact Complained (spam report)
• Email Delivered
• Campaign Sent
• Form Submitted
• Contact Added to List / Removed From List
• Contact Tagged / Untagged

Each item carries event, eventid, occurredat, contactid, email, campaignid, campaignname, any event details (for example subtype), and the full payload. Deliveries are signed with X-MailGraf-Signature; the trigger verifies the signature with the webhook’s secret and rejects anything else with 401.

A MailGraf account can hold up to 10 webhooks, including those created in Settings. Each active trigger node uses one.

Credentials

1. In MailGraf, open Settings > Developers > API and create a key. The key is shown once; copy it.
2. In n8n, create a MailGraf API credential and paste the key. Keep the API base URL unless MailGraf gives you another address.
3. Use the credential in the MailGraf and MailGraf Trigger nodes.

API access depends on the MailGraf plan. If the credential test says the plan does not include API access, upgrade the plan in MailGraf.

Compatibility

Built and tested with n8n 1.x. Requires Node.js 20 or later for building.

Usage

• Google Sheets row → MailGraf contact: Google Sheets Trigger → MailGraf (Contact: Create or Update, choose a list).
• Shop order → automation: your shop’s trigger → MailGraf (Contact: Create or Update) → MailGraf (Event: Send, name order_paid).
• Unsubscribe → CRM: MailGraf Trigger (Contact Unsubscribed) → your CRM node.
• Engagement → CRM, once a day: Schedule Trigger → MailGraf (Contact: Get Many, Updated Since = the previous run) → your CRM node (find the person by email, write temperature, stars and last email open or click).

Resources

• n8n community nodes documentation
• MailGraf API reference
• MailGraf help centre

Version history

• 0.1.1: package contact address corrected.
• 0.1.0: first release with the MailGraf node (contacts, lists, events, campaigns, custom fields) and the MailGraf Trigger node.