SendGrid MCP Server

Instructions

Implementation Reference

• src/tools/templates.ts:304-399 (handler)

  Handler function for 'create_html_template' that creates a new dynamic template and adds an active version with the provided HTML content, subject, and optional plain text/test data using SendGrid API endpoints.

      handler: async ({ 
        template_name, 
        version_name, 
        subject, 
        html_content, 
        plain_content,
        test_data 
      }: { 
        template_name: string; 
        version_name: string; 
        subject: string; 
        html_content: string; 
        plain_content?: string;
        test_data?: string;
      }): Promise<ToolResult> => {
        const readOnlyCheck = checkReadOnlyMode();
        if (readOnlyCheck.blocked) {
          return { content: [{ type: "text", text: readOnlyCheck.message! }] };
        }
        
        try {
          // Step 1: Create the template
          const template = await makeRequest("https://api.sendgrid.com/v3/templates", {
            method: "POST",
            body: JSON.stringify({
              name: template_name,
              generation: "dynamic"
            }),
          });
          
          const template_id = template.id;
          
          // Step 2: Create the version with HTML content
          const versionData: any = {
            name: version_name,
            subject: subject,
            html_content: html_content,
            active: 1,
            generate_plain_content: !plain_content, // Auto-generate if no plain content provided
          };
          
          if (plain_content) {
            versionData.plain_content = plain_content;
          }
          
          if (test_data) {
            try {
              versionData.test_data = JSON.parse(test_data);
            } catch (error) {
              // Delete the template we just created since version failed
              await makeRequest(`https://api.sendgrid.com/v3/templates/${template_id}`, {
                method: "DELETE",
              });
              return { content: [{ type: "text", text: "Error: test_data must be valid JSON. Template creation cancelled." }] };
            }
          }
          
          const version = await makeRequest(`https://api.sendgrid.com/v3/templates/${template_id}/versions`, {
            method: "POST",
            body: JSON.stringify(versionData),
          });
          
          return { 
            content: [{ 
              type: "text", 
              text: `✅ HTML Template created successfully!
  
  📧 Template Details:
  - Template ID: ${template_id}
  - Template Name: ${template_name}
  - Version ID: ${version.id}
  - Version Name: ${version_name}
  - Subject: ${subject}
  - Status: Active and ready to use
  
  🚀 Usage:
  You can now send emails using this template with the Mail API:
  - Use template_id: "${template_id}"
  - Include dynamic_template_data with your Handlebars variables
  
  🔗 Quick Actions:
  - View in SendGrid UI: https://mc.sendgrid.com/dynamic-templates/${template_id}
  - Test the template with sample data in the SendGrid editor
  
  ${JSON.stringify({ template, version }, null, 2)}` 
            }] 
          };
        } catch (error: any) {
          return { 
            content: [{ 
              type: "text", 
              text: `❌ Error creating template: ${error.message || 'Unknown error occurred'}` 
            }] 
          };
        }
      },

• src/tools/templates.ts:295-302 (schema)

  Input schema (Zod validation) for 'create_html_template' defining parameters: template_name, version_name, subject, html_content, plain_content (optional), test_data (optional).

  inputSchema: {
    template_name: z.string().describe("Name of the template"),
    version_name: z.string().describe("Name for the initial version"),
    subject: z.string().describe("Email subject line (supports Handlebars like {{firstName}})"),
    html_content: z.string().describe("Complete HTML email template (supports Handlebars)"),
    plain_content: z.string().optional().describe("Plain text version (will auto-generate if not provided)"),
    test_data: z.string().optional().describe("JSON string with test data for preview (e.g., '{\"firstName\":\"John\",\"company\":\"Acme\"}')")
  },

• src/index.ts:20-23 (registration)

  Registration of all tools (including create_html_template via allTools) to the MCP server using server.registerTool in a loop over Object.entries(allTools).

  // Register all tools
  for (const [name, tool] of Object.entries(allTools)) {
    server.registerTool(name, tool.config as any, tool.handler as any);
  }

• src/tools/index.ts:7-17 (registration)

  Aggregation of templateTools (containing create_html_template) into allTools export via spread operator, after importing from './templates.js'.

  import { templateTools } from "./templates.js";
  
  export const allTools = {
    ...automationTools,
    ...campaignTools,
    ...contactTools,
    ...mailTools,
    ...miscTools,
    ...statsTools,
    ...templateTools,
  };