SendGrid MCP Connector Service

This Model Context Protocol (MCP) intermediary service furnishes access to the SendGrid Marketing API, facilitating the execution of email marketing operations and contact roster administration. This includes functionalities for formulating electronic mail layouts and dispatching messages to specified subscriber assemblies. Reference: https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api

Demonstration Scenario

In this representative execution, the Cline SendGrid agent is instructed to establish a new recipient aggregation, populate it with specified electronic mail addresses, dynamically generate a visual theme based on Lost Cities trivia, and subsequently transmit the resultant communication to that collection. During this sequence, Cline will autonomously ascertain the prerequisites, such as identifying presently verified sender credentials and the appropriate suppression cohort identifier. A visually appealing electronic mail is then successfully delivered to the intended inboxes, providing an enjoyable experience centered around Lost Cities facts!

Crucial Stipulation Regarding API Version Support

This service layer is strictly architected around the SendGrid v3 API specification. It deliberately omits support for deprecated or legacy methods. Specifically:

• Only dynamic template construction methods are supported; legacy template formats are explicitly excluded.
• All cohort and subscriber list manipulations leverage the Marketing API v3 endpoints.
• The Single Sends API mechanism is mandated for all bulk electronic mail transmissions.

Exposed Functionalities

Recipient Cohort Administration

list_contacts

Retrieves a registry of all subscribers associated with your SendGrid tenant. typescript // Zero input parameters necessary

add_contact

Registers a new recipient within SendGrid's marketing contact database. typescript { email: string; // Mandatory: The electronic mail address for the recipient first_name?: string; // Optional: Designated given name last_name?: string; // Optional: Designated surname custom_fields?: object; // Optional: Key-value pairs for user-defined attributes }

delete_contacts

Removes specified recipients from the SendGrid contact repository. typescript { emails: string[]; // Mandatory: An array containing the electronic mail addresses slated for removal }

get_contacts_by_list

Fetches the complete collection of registered recipients linked to a particular SendGrid grouping. typescript { list_id: string; // Mandatory: The unique identifier for the target recipient list }

Grouping Administration

list_contact_lists

Generates a catalog of all recipient groupings configured within your SendGrid environment. typescript // Zero input parameters necessary

create_contact_list

Instantiates a novel recipient grouping within the SendGrid system. typescript { name: string; // Mandatory: The designated label for the new recipient grouping }

delete_list

Decommissions a specified recipient grouping in SendGrid. typescript { list_id: string; // Mandatory: The identifier of the recipient grouping targeted for deletion }

add_contacts_to_list

Enrolls existing recipients into a specified SendGrid grouping. typescript { list_id: string; // Mandatory: The identifier of the recipient grouping to augment emails: string[]; // Mandatory: An array of electronic mail addresses to incorporate }

remove_contacts_from_list

Separates specified recipients from an active SendGrid grouping without purging their records. typescript { list_id: string; // Mandatory: The identifier of the recipient grouping to modify emails: string[]; // Mandatory: An array of electronic mail addresses to disassociate }

Electronic Mail Dispatch

send_email

Transmits a singular electronic mail message utilizing the SendGrid infrastructure. typescript { to: string; // Mandatory: Destination electronic mail recipient address subject: string; // Mandatory: Text string serving as the message header line text: string; // Mandatory: Unformatted textual component of the message body from: string; // Mandatory: Verified electronic mail address of the sender html?: string; // Optional: HyperText Markup Language (HTML) formatted body content template_id?: string; // Optional: Identifier corresponding to a dynamic template dynamic_template_data?: object; // Optional: Structured data objects for template variable substitution }

send_to_list

Dispatches an electronic mail blast to an entire contact grouping using the Single Sends mechanism. typescript { name: string; // Mandatory: Descriptive label for this transmission event list_ids: string[]; // Mandatory: Array of grouping identifiers targeted for reception subject: string; // Mandatory: Subject line for the dispatched correspondence html_content: string; // Mandatory: HTML payload for rich presentation plain_content: string; // Mandatory: Plain-text fallback content sender_id: number; // Mandatory: Numeric identifier for the pre-verified sender identity suppression_group_id?: number; // Required if custom_unsubscribe_url is absent custom_unsubscribe_url?: string; // Required if suppression_group_id is not supplied }

Layout Specification Administration (Dynamic Layouts Exclusively)

create_template

Fabricates a novel dynamic electronic mail layout definition. typescript { name: string; // Mandatory: Designation label for the layout subject: string; // Mandatory: Default subject line embedded in the layout html_content: string; // Mandatory: HTML structure incorporating Handlebars syntax (e.g., {{variable_name}}) plain_content: string; // Mandatory: Plain-text analogue incorporating Handlebars syntax }

list_templates

Retrieves a registry of all dynamically configured electronic mail layouts. typescript // Zero input parameters necessary

get_template

Fetches the specific definition details for a layout identified by its unique ID. typescript { template_id: string; // Mandatory: The identifier referencing the layout to be fetched }

delete_template

Decommissioning operation for a specified dynamic layout. typescript { template_id: string; // Mandatory: The identifier of the dynamic layout slated for erasure }

Performance Metrics and Verification

get_stats

Acquires statistical summaries regarding electronic mail delivery performance. typescript { start_date: string; // Mandatory: Chronological beginning point (Format: YYYY-MM-DD) end_date?: string; // Optional: Chronological endpoint (Format: YYYY-MM-DD) aggregated_by?: 'day' | 'week' | 'month'; // Optional: Temporal granularity for aggregation }

validate_email

Leverages SendGrid's internal mechanisms to verify the deliverability status of an electronic mail address. typescript { email: string; // Mandatory: The electronic mail address undergoing validation }

Account Identity Administration

list_verified_senders

Enumerates all sender identities that have successfully completed verification procedures. typescript // Zero input parameters necessary

list_suppression_groups

Retrieves a catalog of all configured unsubscribe cohorts. typescript // Zero input parameters necessary

Deployment Instructions

bash git clone https://github.com/Garoth/sendgrid-mcp.git cd sendgrid-mcp npm install

Configuration Protocol

1. Obtain your SendGrid Authentication Credential (API Key):
2. Navigate to your SendGrid control panel.
3. Proceed to Settings -> API Keys interface.
4. Generate a novel API key, ensuring it possesses comprehensive operational permissions.

5. Securely store this key, as it will not be displayed again.

6. Incorporate the credential into your Cline MCP configuration file (typically located in VSCode settings, e.g., ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{ "mcpServers": { "sendgrid": { "command": "node", "args": ["/path/to/sendgrid-mcp/build/index.js"], "env": { "SENDGRID_API_KEY": "your-api-key-here" }, "disabled": false, "autoApprove": [ "list_contacts", "list_contact_lists", "list_templates", "list_single_sends", "get_single_send", "list_verified_senders", "list_suppression_groups", "get_stats", "validate_email" ] } } }

Note: Operational routines that effect data state changes (such as transmitting electronic mail or purging recipient records) are intentionally omitted from the automatic approval list as a precautionary measure.

Development Lifecycle

Establishing Test Execution Environment

The integrated verification suite executes live API interactions to guarantee data fidelity in responses. To initiate these tests:

1. Duplicate the template environment file: bash cp .env.example .env

2. Modify the .env file to inject your SendGrid API Key:

SENDGRID_API_KEY=your-api-key-here

Observation: The .env file is configured to be ignored by Git to prevent exposure of secret material.

1. Execute the verification suite: bash npm test

Compilation Process

bash npm run build

Critical Caveats

• When targeting recipient groupings for dispatch, compliance with regulatory mandates necessitates the provision of either a suppression_group_id or a custom_unsubscribe_url.
• Sender electronic mail addresses must attain pre-authorization (verification) by SendGrid prior to their utilization in message origination.
• All instantiated layouts are constructed using the dynamic template standard, offering native support for Handlebars expression syntax (e.g., {{variable_name}}).
• The Single Sends API protocol is the designated method for all high-volume transmission operations due to its superior tracking and administrative capabilities.
• The SendGrid API exhibits characteristics of eventual consistency; alterations to data (such as contact additions or list modifications) might not propagate instantaneously following their execution.

Licensing

MIT

SendGrid logo copyright / property of Twilio

== Conceptual Framework == Business orchestration utilities encompass the entire spectrum of systems, transactional applications, regulatory controls, computational methodologies, and frameworks utilized by organizations to effectively navigate evolving marketplace conditions, maintain competitive positioning, and enhance operational efficacy.

There exists a departmental specialization within these utilities, classifiable by specific management dimensions: for instance, foresight instruments, workflow regulators, archival systems, human capital assets, assessment mechanisms, oversight protocols, etc. A functional categorization addresses these universal aspects:

Utilities employed for data assimilation and correctness checking across any business unit. Instruments dedicated to supervising and refining organizational workflows. Systems for data synthesis and consequential decision-making. Contemporary management utilities have undergone profound transformations over the last decade, driven by rapid technological advancement, creating complexity in selecting optimal solutions for diverse corporate environments. This dynamism is fueled by persistent efforts to minimize expenditure while maximizing revenue realization, the commitment to deeply comprehending clientele necessities, and the drive to supply requisite products precisely as demanded. In this setting, executive leadership should adopt a strategic posture toward these management instruments, resisting the urge to blindly adopt the newest available tool. Often, reliance on unmodified, off-the-shelf utilities leads to systemic fragility. Business management instruments require meticulous vetting, followed by careful alignment with the organization's unique operational mandates, rather than the inverse approach.

== Predominant Instruments == In 2013, a comprehensive analysis by Bain & Company mapped the global deployment of business instruments, reflecting how their resultant outputs addressed regional requirements amid economic fluctuations. The leading ten categories identified were:

Strategic foresight planning Client relationship management systems Employee sentiment measurement Comparative performance analysis (Benchmarking) Balanced scorecard methodology Core organizational capability identification External resource sourcing (Outsourcing) Organizational transition frameworks Logistics and materials flow management Foundational purpose and vision documentation Market demographic differentiation Total quality assurance methodologies

== Commercial Software Applications == Software collections or individual computer programs employed by enterprise personnel to execute diverse organizational functions are termed business software (or enterprise applications). These applications aim to augment productivity levels, quantify performance outcomes, and execute various corporate responsibilities with precision. The evolution traces from early Management Information Systems (MIS) to integrated Enterprise Resource Planning (ERP) frameworks. Subsequently, Customer Relationship Management (CRM) capabilities were integrated, culminating in the current paradigm of cloud-based corporate management suites. While a demonstrable correlation exists between Information Technology investments and organizational results, two elements are critical multipliers for added value: the proficiency of the deployment execution and the accurate selection and subsequent customization of the chosen tools.

== Solutions Tailored for Small and Medium Enterprises (SMEs) == Utilities specifically engineered for SMEs are vital as they furnish pathways for reducing operational outlay...