send_to_list
Send email campaigns to contact lists using SendGrid Single Sends. Define recipients, compose content, and manage unsubscribes for targeted email marketing.
Instructions
Send an email to a contact list using SendGrid Single Sends
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the single send | |
| list_ids | Yes | Array of list IDs to send to | |
| subject | Yes | Email subject line | |
| html_content | Yes | HTML content of the email | |
| plain_content | Yes | Plain text content of the email | |
| sender_id | Yes | ID of the verified sender | |
| suppression_group_id | No | ID of the suppression group for unsubscribes (required if custom_unsubscribe_url not provided) | |
| custom_unsubscribe_url | No | Custom URL for unsubscribes (required if suppression_group_id not provided) |
Implementation Reference
- src/tools/index.ts:494-522 (handler)Handler for the 'send_to_list' tool. Validates unsubscribe settings, creates a SendGrid Single Send targeting the provided list_ids, configures the email, and schedules immediate sending via SendGridService.
case 'send_to_list': if (!args.suppression_group_id && !args.custom_unsubscribe_url) { throw new Error('Either suppression_group_id or custom_unsubscribe_url must be provided'); } const newSingleSend = await service.createSingleSend({ name: args.name, send_to: { list_ids: args.list_ids }, email_config: { subject: args.subject, html_content: args.html_content, plain_content: args.plain_content, sender_id: args.sender_id, suppression_group_id: args.suppression_group_id, custom_unsubscribe_url: args.custom_unsubscribe_url } }); // Schedule it to send immediately await service.scheduleSingleSend(newSingleSend.id, 'now'); return { content: [{ type: 'text', text: `Email "${args.name}" has been sent to the specified lists` }] }; - src/tools/index.ts:286-329 (schema)Input schema definition for the 'send_to_list' tool, defining parameters like name, list_ids, subject, contents, sender_id, and unsubscribe options.
name: 'send_to_list', description: 'Send an email to a contact list using SendGrid Single Sends', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the single send' }, list_ids: { type: 'array', items: { type: 'string' }, description: 'Array of list IDs to send to' }, subject: { type: 'string', description: 'Email subject line' }, html_content: { type: 'string', description: 'HTML content of the email' }, plain_content: { type: 'string', description: 'Plain text content of the email' }, sender_id: { type: 'number', description: 'ID of the verified sender' }, suppression_group_id: { type: 'number', description: 'ID of the suppression group for unsubscribes (required if custom_unsubscribe_url not provided)' }, custom_unsubscribe_url: { type: 'string', description: 'Custom URL for unsubscribes (required if suppression_group_id not provided)' } }, required: ['name', 'list_ids', 'subject', 'html_content', 'plain_content', 'sender_id'] } }, - src/tools/index.ts:4-374 (registration)The getToolDefinitions function registers the 'send_to_list' tool schema by including it in the array of tool definitions exported for use in the MCP server.
export const getToolDefinitions = (service: SendGridService) => [ { name: 'delete_contacts', description: 'Delete contacts from your SendGrid account', inputSchema: { type: 'object', properties: { emails: { type: 'array', items: { type: 'string' }, description: 'Array of email addresses to delete' } }, required: ['emails'] } }, { name: 'list_contacts', description: 'List all contacts in your SendGrid account', inputSchema: { type: 'object', properties: {}, required: [] } }, { name: 'send_email', description: 'Send an email using SendGrid', inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'Recipient email address' }, subject: { type: 'string', description: 'Email subject line' }, text: { type: 'string', description: 'Plain text content of the email' }, html: { type: 'string', description: 'HTML content of the email (optional)' }, from: { type: 'string', description: 'Sender email address (must be verified with SendGrid)' }, template_id: { type: 'string', description: 'SendGrid template ID (optional)' }, dynamic_template_data: { type: 'object', description: 'Dynamic data for template variables (optional)' } }, required: ['to', 'subject', 'text', 'from'] } }, { name: 'add_contact', description: 'Add a contact to your SendGrid marketing contacts', inputSchema: { type: 'object', properties: { email: { type: 'string', description: 'Contact email address' }, first_name: { type: 'string', description: 'Contact first name (optional)' }, last_name: { type: 'string', description: 'Contact last name (optional)' }, custom_fields: { type: 'object', description: 'Custom field values (optional)' } }, required: ['email'] } }, { name: 'create_contact_list', description: 'Create a new contact list in SendGrid', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the contact list' } }, required: ['name'] } }, { name: 'add_contacts_to_list', description: 'Add contacts to an existing SendGrid list', inputSchema: { type: 'object', properties: { list_id: { type: 'string', description: 'ID of the contact list' }, emails: { type: 'array', items: { type: 'string' }, description: 'Array of email addresses to add to the list' } }, required: ['list_id', 'emails'] } }, { name: 'create_template', description: 'Create a new email template in SendGrid', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the template' }, subject: { type: 'string', description: 'Default subject line for the template' }, html_content: { type: 'string', description: 'HTML content of the template' }, plain_content: { type: 'string', description: 'Plain text content of the template' } }, required: ['name', 'subject', 'html_content', 'plain_content'] } }, { name: 'get_template', description: 'Retrieve a SendGrid template by ID', inputSchema: { type: 'object', properties: { template_id: { type: 'string', description: 'ID of the template to retrieve' } }, required: ['template_id'] } }, { name: 'delete_template', description: 'Delete a dynamic template from SendGrid', inputSchema: { type: 'object', properties: { template_id: { type: 'string', description: 'ID of the template to delete' } }, required: ['template_id'] } }, { name: 'validate_email', description: 'Validate an email address using SendGrid', inputSchema: { type: 'object', properties: { email: { type: 'string', description: 'Email address to validate' } }, required: ['email'] } }, { name: 'get_stats', description: 'Get SendGrid email statistics', inputSchema: { type: 'object', properties: { start_date: { type: 'string', description: 'Start date in YYYY-MM-DD format' }, end_date: { type: 'string', description: 'End date in YYYY-MM-DD format (optional)' }, aggregated_by: { type: 'string', enum: ['day', 'week', 'month'], description: 'How to aggregate the statistics (optional)' } }, required: ['start_date'] } }, { name: 'list_templates', description: 'List all email templates in your SendGrid account', inputSchema: { type: 'object', properties: {}, required: [] } }, { name: 'delete_list', description: 'Delete a contact list from SendGrid', inputSchema: { type: 'object', properties: { list_id: { type: 'string', description: 'ID of the contact list to delete' } }, required: ['list_id'] } }, { name: 'list_contact_lists', description: 'List all contact lists in your SendGrid account', inputSchema: { type: 'object', properties: {}, required: [] } }, { 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'] } }, { name: 'list_verified_senders', description: 'List all verified sender identities in your SendGrid account', inputSchema: { type: 'object', properties: {}, required: [] } }, { name: 'list_suppression_groups', description: 'List all unsubscribe groups in your SendGrid account', inputSchema: { type: 'object', properties: {}, required: [] } }, { name: 'send_to_list', description: 'Send an email to a contact list using SendGrid Single Sends', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the single send' }, list_ids: { type: 'array', items: { type: 'string' }, description: 'Array of list IDs to send to' }, subject: { type: 'string', description: 'Email subject line' }, html_content: { type: 'string', description: 'HTML content of the email' }, plain_content: { type: 'string', description: 'Plain text content of the email' }, sender_id: { type: 'number', description: 'ID of the verified sender' }, suppression_group_id: { type: 'number', description: 'ID of the suppression group for unsubscribes (required if custom_unsubscribe_url not provided)' }, custom_unsubscribe_url: { type: 'string', description: 'Custom URL for unsubscribes (required if suppression_group_id not provided)' } }, required: ['name', 'list_ids', 'subject', 'html_content', 'plain_content', 'sender_id'] } }, { name: 'get_single_send', description: 'Get details of a specific single send', inputSchema: { type: 'object', properties: { single_send_id: { type: 'string', description: 'ID of the single send to retrieve' } }, required: ['single_send_id'] } }, { name: 'list_single_sends', description: 'List all single sends in your SendGrid account', inputSchema: { type: 'object', properties: {}, required: [] } }, { name: 'remove_contacts_from_list', description: 'Remove contacts from a SendGrid list without deleting them', inputSchema: { type: 'object', properties: { list_id: { type: 'string', description: 'ID of the contact list' }, emails: { type: 'array', items: { type: 'string' }, description: 'Array of email addresses to remove from the list' } }, required: ['list_id', 'emails'] } } ];