Omnisend Contacts & Tags

Name: Omnisend Contacts & Tags
Author: vx.ai

v1.0.0 · 6 endpoints · 0 connections · shared by vx.ai

For online stores that email and text through Omnisend: look up a shopper by email or phone, see their email and SMS consent, add or update subscribers with custom properties, and tag whole groups (a list of emails, phones or a segment) so the right automation picks them up.

Connect this API to an AI agent Browse all specs

What you can do with Omnisend Contacts & Tags via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/contacts`	listContacts	List or find contacts by email, phone, status, segment or tag
POST	`/contacts`	upsertContact	Add a contact, or update it if the email or phone exists
PATCH	`/contacts`	updateContactByEmail	Update the contact with a given email address
GET	`/contacts/{id}`	getContact	Get a contact with consent status, tags and custom properties
PATCH	`/contacts/{id}`	updateContact	Update a contact by its Omnisend id
POST	`/contacts/tags`	addTagsToContacts	Add tags to contacts by id, email, phone or segment

Authentication

omnisendApiKey

API key — sent as the Authorization header

Omnisend API key sent in the Authorization header as Omnisend-API-Key <your key>. Save the whole value, including the Omnisend-API-Key prefix, as the credential.

How to get a credential

In Omnisend, open Store settings > API keys (app.omnisend.com/integrations/api-keys).
Click Create API key, name it (e.g. VX Agents).
Under permissions, give Contacts read and write access.
Copy the key and save it as Omnisend-API-Key <key>.

Permissions used

Permission	Operations
Contacts: read (`contacts.read`)	listContacts, getContact
Contacts: write (`contacts.write`)	upsertContact, updateContactByEmail, updateContact, addTagsToContacts

Common errors

401 Unauthorized: the header is missing the Omnisend-API-Key prefix, or the key was deleted. Re-create the key and save it with the prefix.
403 Forbidden: the key has no Contacts permission. Edit the key's permissions.
400 Bad Request: invalid filter combination (e.g. tag with status, or updatedAtFrom with other filters), a missing Omnisend-Version header, or a phone not in E.164 format.
404 Not Found: no contact with that id or email.
429 Too Many Requests: limit is 400 requests per minute per endpoint; wait and retry.

Store the key as a VX Agents credential so it is never pasted into chat.

Usage guide

Setup

Add an API key credential with the value Omnisend-API-Key <your key> (Store settings > API keys, Contacts read + write). It is sent in the Authorization header.
Every call sends Omnisend-Version: 2026-03-15; it is preset, leave it as is.

Look up a shopper

listContacts with email or phone (E.164, e.g. +14155550100) to find one contact, or with tag, status (subscribed, unsubscribed, nonSubscribed) or segmentID to list a group. updatedAtFrom (RFC 3339) lists recent changes but cannot be combined with the other filters, and tag cannot be combined with status.
getContact with the contact id for identifiers, per-channel status (email, sms), tags and customProperties.
Page with limit (up to 250) and the after cursor from paging.cursors.after.

Add or update subscribers

Show the user the change and wait for confirmation: subscribing someone makes them eligible for marketing messages.

upsertContact creates or updates by email/phone. Body: identifiers: [{"type": "email", "id": "[email protected]", "channels": {"email": {"status": "subscribed"}}}] plus firstName, lastName, tags, customProperties, address fields. Only mark subscribed when the shopper actually opted in.
updateContactByEmail (query email) or updateContact (path id) change an existing contact; send only the fields that change.

Tag a group

addTagsToContacts with tags (1-100) and any of contactIDs, emails, phones (up to 250 each) or a segmentID. Tagging runs asynchronously, so new tags can take a moment to show; unknown emails/phones are ignored. Tags often start automations, so confirm first.

Good to know

Phone numbers are E.164; dates are ISO 8601 / RFC 3339; birthdate is YYYY-MM-DD.
Rate limit is 400 requests per minute per endpoint.
This spec cannot delete contacts or remove tags.

Source: Omnisend API reference (https://api-docs.omnisend.com/reference/overview), checked 2026-10-21.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Omnisend Contacts & Tags” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.