get_contacts_by_list

Retrieve all contacts from a specific SendGrid email list using the list ID to manage and organize your email marketing recipients.

Instructions

Get all contacts in a SendGrid list

Input Schema

TableJSON Schema

Name	Required	Description	Default
`list_id`	Yes	ID of the contact list

Implementation Reference

src/tools/index.ts:463-474 (handler)

The handler logic within handleToolCall that executes the 'get_contacts_by_list' tool. It calls the SendGrid service method with the provided list_id and returns a formatted JSON string of the contacts (email, first_name, last_name).

case 'get_contacts_by_list':
  const contacts = await service.getContactsByList(args.list_id);
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(contacts.map(c => ({
        email: c.email,
        first_name: c.first_name,
        last_name: c.last_name
      })), null, 2)
    }]
  };

src/tools/index.ts:253-266 (schema)

Input schema and tool definition (registration) for 'get_contacts_by_list', requiring a 'list_id' string parameter.

{
  name: 'get_contacts_by_list',
  description: 'Get all contacts in a SendGrid list',
  inputSchema: {
    type: 'object',
    properties: {
      list_id: {
        type: 'string',
        description: 'ID of the contact list'
      }
    },
    required: ['list_id']
  }
},

src/services/sendgrid.ts:75-84 (helper)

Core helper method in SendGridService that queries the SendGrid Marketing Contacts Search API to retrieve all contacts belonging to the specified list using a CONTAINS query on list_ids.

async getContactsByList(listId: string): Promise<SendGridContact[]> {
  const [response] = await this.client.request({
    method: 'POST',
    url: '/v3/marketing/contacts/search',
    body: {
      query: `CONTAINS(list_ids, '${listId}')`
    }
  });
  return (response.body as { result: SendGridContact[] }).result || [];
}

src/index.ts:42-46 (registration)
MCP server registration for listing tools, which includes 'get_contacts_by_list' via getToolDefinitions.
```
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: getToolDefinitions(sendGridService)
  };
});
```

src/index.ts:52-55 (registration)

MCP server handler for tool calls, delegating to handleToolCall which processes 'get_contacts_by_list'.

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  try {
    return await handleToolCall(sendGridService, request.params.name, request.params.arguments);
  } catch (error: any) {

SendGrid MCP Server