lunartech-x/Omnisend Automation

Omnisend Automation

Automate ecommerce marketing operations -- create and update contacts, manage subscriber lists with cursor pagination, run bulk batch operations, and segment audiences -- all orchestrated through the Composio MCP integration.

Toolkit docs: composio.dev/toolkits/omnisend

---

Setup

1. Connect your Omnisend account through the Composio MCP server at https://rube.app/mcp
2. The agent will prompt you with an authentication link if no active connection exists
3. Once connected, all OMNISEND_* tools become available for execution

---

Core Workflows

1. Create or Update a Contact

Upsert a contact by email identifier with subscription status, profile fields, and optional welcome message.

Tool: OMNISEND_CREATE_OR_UPDATE_CONTACT

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | identifiers | array | Yes | At least one identifier object with id (email), type (email), optional channels.email.status (subscribed, nonSubscribed, unsubscribed), and sendWelcomeMessage (boolean) | | firstName | string | No | Contact's first name | | lastName | string | No | Contact's last name | | gender | string | No | m or f | | birthdate | string | No | Format: YYYY-MM-DD | | country | string | No | Full country name | | countryCode | string | No | ISO 3166-1 alpha-2 code (e.g., US) | | city | string | No | City name | | address | string | No | Street address | | postalCode | string | No | ZIP/postal code |

---

2. List Contacts with Pagination

Retrieve contacts in batches with optional filters for email, phone, status, segment, or tag.

Tool: OMNISEND_LIST_CONTACTS

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | limit | integer | No | Results per page (default: 100, max: 250) | | after | string | No | Cursor for next page (base64-encoded ContactID) | | before | string | No | Cursor for previous page | | email | string | No | Filter by exact email address | | phone | string | No | Filter by full phone number with country code | | status | string | No | Filter by: subscribed, nonSubscribed, unsubscribed | | segmentID | integer | No | Filter by segment ID | | tag | string | No | Filter by tag (e.g., VIP) |

---

3. Get Contact Details

Retrieve the full profile for a single contact when you already have their contact ID.

Tool: OMNISEND_GET_CONTACT

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | contactId | string | Yes | Unique contact identifier (e.g., 60e7412b1234567890abcdef) |

---

4. Update an Existing Contact

Patch specific fields on a contact by ID without overwriting the entire record.

Tool: OMNISEND_UPDATE_CONTACT

Requires the contactId and the fields to update. Retrieve the contact ID first via OMNISEND_LIST_CONTACTS or OMNISEND_GET_CONTACT.

---

5. Bulk Batch Operations

Process many records asynchronously in a single call -- contacts, products, orders, events, or categories.

Tool: OMNISEND_CREATE_BATCH

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | method | string | Yes | POST or PUT | | endpoint | string | Yes | Target: contacts, orders, products, events, categories | | items | array | Yes | Array of payload objects for each operation | | eventID | string | Conditional | Required when endpoint is events |

Use batch operations to avoid rate limits when processing large data sets.

---

Known Pitfalls

| Pitfall | Details | |---------|---------| | Identifier required | OMNISEND_CREATE_OR_UPDATE_CONTACT requires at least one identifier in the identifiers array -- only email type is supported | | Cursor-based pagination | OMNISEND_LIST_CONTACTS uses base64-encoded after/before cursors, not page numbers -- follow cursors to avoid incomplete data | | Contact ID resolution | OMNISEND_UPDATE_CONTACT requires a contactId -- always resolve it first via list or get operations | | Batch method constraints | OMNISEND_CREATE_BATCH only accepts POST or PUT methods -- no DELETE or PATCH | | Event ID dependency | When batching events, the eventID parameter is mandatory -- omitting it causes the batch to fail |

---

Quick Reference

| Tool Slug | Purpose | |-----------|---------| | OMNISEND_CREATE_OR_UPDATE_CONTACT | Create or upsert a contact by email | | OMNISEND_LIST_CONTACTS | List contacts with filtering and cursor pagination | | OMNISEND_GET_CONTACT | Get full profile for a single contact by ID | | OMNISEND_UPDATE_CONTACT | Patch specific fields on an existing contact | | OMNISEND_CREATE_BATCH | Bulk async operations for contacts, products, orders, events |

---

Powered by Composio