listContacts
Retrieve a filtered list of contacts from Omnisend, including email, phone, and subscription status, for precise audience management and segmentation.
Instructions
Retrieve a list of contacts from Omnisend. Each contact can be identified by multiple identifiers (email, phone) with corresponding channels.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of contacts to return | |
| offset | No | Skip first N results | |
| status | No | Filter contacts by subscription status |
Implementation Reference
- src/tools/contacts/index.ts:24-48 (handler)MCP tool handler for 'listContacts': invokes the API helper with args, filters the contacts using filterContactFields, formats the response as JSON text content with pagination.async (args) => { try { const response = await listContacts(args); // Filter contacts data to include only defined fields const filteredContacts = response.contacts.map(filterContactFields); return { content: [ { type: "text", text: JSON.stringify({ contacts: filteredContacts, paging: response.paging }, null, 2) } ] }; } catch (error) { if (error instanceof Error) { return { content: [{ type: "text", text: `Error: ${error.message}` }] }; } return { content: [{ type: "text", text: "An unknown error occurred" }] }; } }
- src/tools/contacts/index.ts:10-23 (schema)Input schema definition for the listContacts tool, including parameters like limit, offset, filters for email, phone, status, dates, and tags.{ additionalProperties: false, properties: { limit: { description: "Maximum number of contacts to return", type: "number" }, offset: { description: "Skip first N results", type: "number" }, email: { description: "Filter contacts by email address", type: "string" }, phone: { description: "Filter contacts by phone number", type: "string" }, status: { description: "Filter contacts by subscription status", enum: ["subscribed", "unsubscribed", "nonSubscribed"], type: "string" }, createdAfter: { description: "Filter contacts created after specified date (ISO format)", type: "string" }, updatedAfter: { description: "Filter contacts updated after specified date (ISO format)", type: "string" }, tags: { description: "Filter contacts by tags", items: { type: "string" }, type: "array" } }, type: "object" },
- src/tools/contacts/index.ts:7-49 (registration)Registration of the 'listContacts' MCP tool on the server, including name, description, input schema, and handler function.server.tool( "listContacts", "Retrieve a list of contacts from Omnisend. Each contact can be identified by multiple identifiers (email, phone) with corresponding channels. The response includes pagination information (next/previous cursor, limit, offset).", { additionalProperties: false, properties: { limit: { description: "Maximum number of contacts to return", type: "number" }, offset: { description: "Skip first N results", type: "number" }, email: { description: "Filter contacts by email address", type: "string" }, phone: { description: "Filter contacts by phone number", type: "string" }, status: { description: "Filter contacts by subscription status", enum: ["subscribed", "unsubscribed", "nonSubscribed"], type: "string" }, createdAfter: { description: "Filter contacts created after specified date (ISO format)", type: "string" }, updatedAfter: { description: "Filter contacts updated after specified date (ISO format)", type: "string" }, tags: { description: "Filter contacts by tags", items: { type: "string" }, type: "array" } }, type: "object" }, async (args) => { try { const response = await listContacts(args); // Filter contacts data to include only defined fields const filteredContacts = response.contacts.map(filterContactFields); return { content: [ { type: "text", text: JSON.stringify({ contacts: filteredContacts, paging: response.paging }, null, 2) } ] }; } catch (error) { if (error instanceof Error) { return { content: [{ type: "text", text: `Error: ${error.message}` }] }; } return { content: [{ type: "text", text: "An unknown error occurred" }] }; } } );
- Helper function that performs the actual Omnisend API GET request to '/contacts' with query params and returns ContactsResponse.export const listContacts = async (params: ListContactsParams = {}): Promise<ContactsResponse> => { try { // Pridėkime trumpą užlaikymą, kad išvengtume daug užklausų per trumpą laiką const response = await omnisendApi.get<ContactsResponse>('/contacts', { params }); return response.data; } catch (error) { // Pagerinkime klaidos apdorojimą if (error instanceof Error) { throw new Error(`Error getting contacts list: ${error.message}`); } else { throw new Error('Unknown error occurred when getting contacts list'); } } };