Create Template Version

Instructions

Implementation Reference

• src/tools/templates.ts:124-179 (handler)

  The handler function for create_template_version. Calls SendGrid POST /v3/templates/{template_id}/versions to create a new template version with HTML content, subject, and optional plain_content, test_data, active, generate_plain_content settings. Returns version details and template_id.

  handler: async ({ 
    template_id, 
    name, 
    subject, 
    html_content, 
    plain_content, 
    active, 
    generate_plain_content, 
    test_data 
  }: { 
    template_id: string; 
    name: string; 
    subject: string; 
    html_content: string; 
    plain_content?: string; 
    active?: number; 
    generate_plain_content?: boolean; 
    test_data?: string; 
  }): Promise<ToolResult> => {
    const readOnlyCheck = checkReadOnlyMode();
    if (readOnlyCheck.blocked) {
      return { content: [{ type: "text", text: readOnlyCheck.message! }] };
    }
    
    const versionData: any = {
      name,
      subject,
      html_content,
      active: active ?? 1,
      generate_plain_content: generate_plain_content ?? true,
    };
    
    if (plain_content) {
      versionData.plain_content = plain_content;
    }
    
    if (test_data) {
      try {
        versionData.test_data = JSON.parse(test_data);
      } catch (error) {
        return { content: [{ type: "text", text: "Error: test_data must be valid JSON" }] };
      }
    }
    
    const result = await makeRequest(`https://api.sendgrid.com/v3/templates/${template_id}/versions`, {
      method: "POST",
      body: JSON.stringify(versionData),
    });
    
    return { 
      content: [{ 
        type: "text", 
        text: `Template version created successfully!\n\n${JSON.stringify(result, null, 2)}\n\nYou can now use this template with the Mail API using template_id: ${template_id}` 
      }] 
    };
  },

• src/tools/templates.ts:110-123 (schema)

  Input schema for create_template_version defining required fields (template_id, name, subject, html_content) and optional fields (plain_content, active with default 1, generate_plain_content with default true, test_data as JSON string).

  config: {
    title: "Create Template Version",
    description: "Create a new version of a template with HTML content and settings",
    inputSchema: {
      template_id: z.string().describe("ID of the template to add version to"),
      name: z.string().describe("Name for this version"),
      subject: z.string().describe("Email subject line (supports Handlebars)"),
      html_content: z.string().describe("HTML content of the email template (supports Handlebars)"),
      plain_content: z.string().optional().describe("Plain text version (optional)"),
      active: z.number().optional().default(1).describe("Set as active version (1 = active, 0 = inactive)"),
      generate_plain_content: z.boolean().optional().default(true).describe("Auto-generate plain text from HTML"),
      test_data: z.string().optional().describe("JSON string of test data for Handlebars variables"),
    },
  },

• src/tools/templates.ts:109-180 (registration)

  The tool definition within the templateTools export object. The key 'create_template_version' is the tool name registered with the MCP server.

  create_template_version: {
    config: {
      title: "Create Template Version",
      description: "Create a new version of a template with HTML content and settings",
      inputSchema: {
        template_id: z.string().describe("ID of the template to add version to"),
        name: z.string().describe("Name for this version"),
        subject: z.string().describe("Email subject line (supports Handlebars)"),
        html_content: z.string().describe("HTML content of the email template (supports Handlebars)"),
        plain_content: z.string().optional().describe("Plain text version (optional)"),
        active: z.number().optional().default(1).describe("Set as active version (1 = active, 0 = inactive)"),
        generate_plain_content: z.boolean().optional().default(true).describe("Auto-generate plain text from HTML"),
        test_data: z.string().optional().describe("JSON string of test data for Handlebars variables"),
      },
    },
    handler: async ({ 
      template_id, 
      name, 
      subject, 
      html_content, 
      plain_content, 
      active, 
      generate_plain_content, 
      test_data 
    }: { 
      template_id: string; 
      name: string; 
      subject: string; 
      html_content: string; 
      plain_content?: string; 
      active?: number; 
      generate_plain_content?: boolean; 
      test_data?: string; 
    }): Promise<ToolResult> => {
      const readOnlyCheck = checkReadOnlyMode();
      if (readOnlyCheck.blocked) {
        return { content: [{ type: "text", text: readOnlyCheck.message! }] };
      }
      
      const versionData: any = {
        name,
        subject,
        html_content,
        active: active ?? 1,
        generate_plain_content: generate_plain_content ?? true,
      };
      
      if (plain_content) {
        versionData.plain_content = plain_content;
      }
      
      if (test_data) {
        try {
          versionData.test_data = JSON.parse(test_data);
        } catch (error) {
          return { content: [{ type: "text", text: "Error: test_data must be valid JSON" }] };
        }
      }
      
      const result = await makeRequest(`https://api.sendgrid.com/v3/templates/${template_id}/versions`, {
        method: "POST",
        body: JSON.stringify(versionData),
      });
      
      return { 
        content: [{ 
          type: "text", 
          text: `Template version created successfully!\n\n${JSON.stringify(result, null, 2)}\n\nYou can now use this template with the Mail API using template_id: ${template_id}` 
        }] 
      };
    },
  },

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

  Where all tools including create_template_version are registered with the MCP server via server.registerTool(name, config, handler).

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

• src/prompts/help.ts:742-773 (helper)

  Help text describing create_template_version as 'Create a new version with HTML content and settings' within the Template Version Management section.

  Template Version Management:
  - create_template_version: Create a new version with HTML content and settings
  - get_template_version: Get details of a specific template version
  - update_template_version: Update version content and settings  
  - delete_template_version: Delete a specific version
  
  AI-Friendly Tools:
  - create_html_template: Create complete template with HTML in one step (perfect for AI)
  - open_template_editor: Open SendGrid's visual editor in browser
  
  What are Dynamic Templates?
  Dynamic templates are reusable email templates that support Handlebars syntax for personalization. They're perfect for transactional emails like welcome messages, receipts, password resets, and notifications.
  
  Key Features:
  - Handlebars syntax: {{firstName}}, {{#each items}}, {{#if condition}}
  - Dynamic content replacement at send time
  - HTML and plain text versions
  - Test data for preview
  - Version management (up to 300 versions per template)
  - Visual editor integration
  
  Creating Templates with AI:
  
  1. Simple Approach - Use create_html_template:
     - Provide: template name, subject, HTML content
     - Supports Handlebars variables like {{name}}, {{company}}
     - Creates template and version in one step
  
  2. Advanced Approach - Multi-step:
     - create_template: Create base template
     - create_template_version: Add HTML content and settings
     - Allows for multiple versions and complex configurations