n8n-nodes-omnisend

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node for Omnisend, the omnichannel marketing automation platform for e-commerce. This node enables workflow automation for contacts, campaigns, e-commerce events, product catalog sync, and multi-channel marketing across email, SMS, and push notifications.

Features

• 10 Resource Categories with 50+ operations
• Multi-channel Contact Management - Email, SMS, and push notification subscriptions
• E-commerce Event Tracking - Orders, carts, product views, and custom events
• Product Catalog Sync - Full product and category management with variants
• Campaign Analytics - Performance metrics and campaign management
• Automation Triggering - Trigger custom automations programmatically
• Segment Management - Access dynamic and static segments
• Form Analytics - Track popup, embedded, and flyout form performance

Installation

Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install
4. Enter n8n-nodes-omnisend
5. Click Install
6. Restart n8n when prompted

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-omnisend

# Restart n8n

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-omnisend.git
cd n8n-nodes-omnisend

# Install dependencies
npm install

# Build the project
npm run build

# Create symlink to n8n custom nodes directory
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-omnisend

# Restart n8n

Credentials Setup

Omnisend API Key

| Field | Description | |-------|-------------| | API Key | Your Omnisend API key from Store Settings → API Keys |

To obtain your API key:

1. Log in to your Omnisend dashboard
2. Navigate to Store Settings → API Keys
3. Click Create API Key
4. Copy the generated key and paste it into n8n

Resources & Operations

Contact

Manage subscriber contacts across all channels.

| Operation | Description | |-----------|-------------| | Create | Create a new contact with email/phone identifiers | | Get | Retrieve contact by ID or email | | Get All | List all contacts with filters | | Update | Update contact details and preferences | | Delete | Remove a contact | | Get Activities | Get activity history for a contact | | Add Tag | Add a tag to a contact | | Remove Tag | Remove a tag from a contact | | Update Identifiers | Update email or phone identifiers |

Campaign

Manage email, SMS, and push notification campaigns.

| Operation | Description | |-----------|-------------| | Get | Retrieve campaign by ID | | Get All | List all campaigns with filters | | Get Stats | Get campaign performance metrics | | Cancel | Cancel a scheduled campaign |

Event

Track e-commerce and custom events.

| Operation | Description | |-----------|-------------| | Track | Send a custom event | | Track Order | Send order placed event | | Track Cart | Send cart updated/abandoned event | | Track Product View | Send product view event | | Get All | List events for a contact |

Product

Manage product catalog.

| Operation | Description | |-----------|-------------| | Create | Add a product to the catalog | | Get | Retrieve product by ID | | Get All | List all products | | Update | Update product details | | Delete | Remove a product | | Sync | Bulk sync products |

Category

Manage product categories.

| Operation | Description | |-----------|-------------| | Create | Create a new category | | Get | Retrieve category by ID | | Get All | List all categories | | Update | Update category details | | Delete | Remove a category |

Order

Track and manage orders.

| Operation | Description | |-----------|-------------| | Create | Create a new order | | Get | Retrieve order by ID | | Get All | List all orders | | Update | Update order status | | Delete | Remove an order |

Cart

Track shopping carts for abandoned cart recovery.

| Operation | Description | |-----------|-------------| | Create | Create/track a cart | | Get | Retrieve cart by ID | | Get All | List all carts | | Update | Update cart contents | | Delete | Remove a cart |

Automation

Manage and trigger automations.

| Operation | Description | |-----------|-------------| | Get | Retrieve automation by ID | | Get All | List all automations | | Get Stats | Get automation performance data | | Trigger | Trigger a custom automation |

Segment

Access contact segments.

| Operation | Description | |-----------|-------------| | Get | Retrieve segment by ID | | Get All | List all segments | | Get Contacts | List contacts in a segment |

Form

Track form performance.

| Operation | Description | |-----------|-------------| | Get | Retrieve form by ID | | Get All | List all forms | | Get Stats | Get form performance metrics |

Usage Examples

Create a Contact

// Node configuration
{
  "resource": "contact",
  "operation": "create",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "emailStatus": "subscribed",
  "tags": "newsletter,vip"
}

Track an Order Event

// Node configuration
{
  "resource": "event",
  "operation": "trackOrder",
  "email": "[email protected]",
  "orderID": "ORD-12345",
  "currency": "USD",
  "orderSum": 99.99,
  "paymentStatus": "paid",
  "fulfillmentStatus": "unfulfilled",
  "lineItems": [
    {
      "productID": "SKU-001",
      "productTitle": "Widget Pro",
      "quantity": 2,
      "price": 49.99
    }
  ]
}

Sync Products

// Node configuration
{
  "resource": "product",
  "operation": "sync",
  "products": [
    {
      "productID": "SKU-001",
      "title": "Widget Pro",
      "price": 49.99,
      "currency": "USD",
      "productUrl": "https://store.example.com/products/widget-pro",
      "imageUrl": "https://store.example.com/images/widget-pro.jpg",
      "status": "inStock"
    }
  ]
}

Omnisend Concepts

Contact Identifiers

Contacts can be identified by:

• Email: Primary identifier for email marketing
• Phone: E.164 format (e.g., +12025551234) for SMS marketing
• Contact ID: Omnisend's internal identifier

Channel Status

Each channel (email, SMS, push) has its own subscription status:

• subscribed: Opted in to receive messages
• unsubscribed: Opted out of messages
• nonSubscribed: Has identifier but hasn't opted in

Event Schema

Events use version 2 schema with:

• eventName: Type of event (e.g., "placed order")
• eventID: Unique identifier for idempotency
• origin: Source of event (use "api")
• contact: Email or phone identifier
• properties: Event-specific data

API Information

| Property | Value | |----------|-------| | Base URL | https://api.omnisend.com/v5 | | Rate Limit | 100 requests/minute | | Pagination | Offset/limit (max 250/page) |

Error Handling

The node handles common Omnisend API errors:

| Status Code | Meaning | |-------------|---------| | 200/201 | Success | | 400 | Bad request - Check parameters | | 401 | Invalid API key | | 403 | Forbidden - Check permissions | | 404 | Resource not found | | 422 | Validation error | | 429 | Rate limited - Slow down requests |

Security Best Practices

1. Store API keys securely - Use n8n credentials, never hardcode
2. Limit API key scope - Create keys with minimal required permissions
3. Monitor usage - Check Omnisend dashboard for unusual activity
4. Rotate keys regularly - Generate new keys periodically
5. Use HTTPS only - All API calls use encrypted connections

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode development
npm run dev

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code passes linting and tests before submitting.

Support

• Documentation: Omnisend API Docs
• Issues: GitHub Issues
• n8n Community: n8n Community Forum

Acknowledgments

• Omnisend for their comprehensive marketing API
• n8n for the workflow automation platform
• The open-source community for inspiration and support