MCP Server SendGrid — transactional email, bounce management, and /health via GET /scopes

SDK setup and authentication

SendGrid provides the @sendgrid/mail package for mail sending and @sendgrid/client for other API operations. Using both gives full coverage. Set API key via the setter rather than passing it per-call.

import sgMail from '@sendgrid/mail';
import sgClient from '@sendgrid/client';
import { z } from 'zod';

// API keys start with SG.
// Always use restricted API keys scoped to minimum required permissions:
// - mail.send — to send email
// - suppression.read — to list bounces/blocks
// - suppression.delete — to remove bounces
// Never use the full-access key in production MCP servers.
sgMail.setApiKey(process.env.SENDGRID_API_KEY!);
sgClient.setApiKey(process.env.SENDGRID_API_KEY!);

// For raw HTTP, all v3 endpoints are:
// https://api.sendgrid.com/v3/{resource}
// Authorization: Bearer SG.your-api-key-here
// Content-Type: application/json

// Rate limit headers on every response:
//   X-RateLimit-Limit: 600       (requests per minute)
//   X-RateLimit-Remaining: 599   (remaining this minute)
//   X-RateLimit-Reset: 1720534860 (Unix timestamp when limit resets)

Sending email with Dynamic Template support and confirm guards

SendGrid Dynamic Templates allow structured email with Handlebars variable substitution, separating content from code. The template_id parameter replaces subject, HTML, and plain text when provided — the API ignores subject and content fields when a template is set. The from address must match a verified Sender Identity or a domain with valid DNS records including DKIM and SPF.

server.tool('send_email', {
  to: z.union([
    z.string().email(),
    z.array(z.object({
      email: z.string().email(),
      name: z.string().optional()
    }))
  ]).describe('Recipient email or array of recipients.'),
  from: z.object({
    email: z.string().email().describe('Must be a verified Sender Identity.'),
    name: z.string().optional()
  }),
  subject: z.string().optional().describe('Email subject. Ignored if template_id is set.'),
  text_content: z.string().optional().describe('Plain text body. Ignored if template_id is set.'),
  html_content: z.string().optional().describe('HTML body. Ignored if template_id is set.'),
  template_id: z.string().optional().describe('SendGrid Dynamic Template ID (d-xxxx). Overrides subject and content.'),
  template_data: z.record(z.unknown()).optional().describe('Handlebars variables for Dynamic Template.'),
  confirm: z.literal(true).describe('Emails cannot be recalled after acceptance. Pass true to confirm.')
}, async ({ to, from, subject, text_content, html_content, template_id, template_data }) => {
  const recipients = Array.isArray(to)
    ? to
    : [{ email: to as string }];

  const msg: sgMail.MailDataRequired = {
    to: recipients,
    from,
    ...(template_id
      ? {
          templateId: template_id,
          dynamicTemplateData: template_data ?? {}
        }
      : {
          subject: subject!,
          content: [
            ...(text_content ? [{ type: 'text/plain', value: text_content }] : []),
            ...(html_content ? [{ type: 'text/html', value: html_content }] : [])
          ]
        }
    )
  };

  const [response] = await sgMail.send(msg);

  // HTTP 202 Accepted — email queued, not yet delivered
  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        accepted: response.statusCode === 202,
        status_code: response.statusCode,
        // Message-Id header returned on successful queue
        message_id: response.headers['x-message-id']
      }, null, 2)
    }]
  };
});

Managing suppression lists for deliverability

Suppression lists prevent SendGrid from re-sending to addresses that have previously bounced, unsubscribed, or been blocked. When an email bounces, SendGrid adds it to the bounce list and will silently skip future sends to that address — important for diagnosing why certain recipients stop receiving messages. The list_bounces and remove_bounce tools let agents surface and remediate deliverability issues.

server.tool('list_bounces', {
  start_time: z.number().int().optional().describe('Unix timestamp. Filter bounces after this time.'),
  end_time: z.number().int().optional().describe('Unix timestamp. Filter bounces before this time.'),
  limit: z.number().int().min(1).max(500).default(100),
  offset: z.number().int().min(0).default(0)
}, async ({ start_time, end_time, limit, offset }) => {
  const query = new URLSearchParams({ limit: String(limit), offset: String(offset) });
  if (start_time) query.set('start_time', String(start_time));
  if (end_time) query.set('end_time', String(end_time));

  const [response, body] = await sgClient.request({
    method: 'GET',
    url: `/v3/suppression/bounces?${query}`
  });

  const bounces = (body as Array<{
    created: number;
    email: string;
    reason: string;
    status: string;
  }>).map(b => ({
    email: b.email,
    reason: b.reason,
    status: b.status,  // e.g. '5.1.1' = invalid address, '5.5.0' = spam rejection
    created_at: new Date(b.created * 1000).toISOString()
  }));

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({ count: bounces.length, bounces }, null, 2)
    }]
  };
});

server.tool('list_blocks', {
  limit: z.number().int().min(1).max(500).default(100),
  offset: z.number().int().min(0).default(0)
}, async ({ limit, offset }) => {
  const [, body] = await sgClient.request({
    method: 'GET',
    url: `/v3/suppression/blocks?limit=${limit}&offset=${offset}`
  });

  return {
    content: [{
      type: 'text',
      text: JSON.stringify(body, null, 2)
    }]
  };
});

Removing bounces to reactivate recipients

Once a bounce is cleared, SendGrid will attempt delivery to that address again. This is appropriate when the bounce was transient (e.g. a full mailbox that has since been emptied) or when the user provides a new valid email address. The remove bounce operation is destructive — misuse will cause emails to be sent to invalid addresses and damage your sender reputation.

server.tool('remove_bounce', {
  email: z.string().email().describe('Email address to remove from the bounce list.'),
  confirm: z.literal(true).describe('Removing a bounce reactivates future sends to this address. Confirm.')
}, async ({ email }) => {
  const [response] = await sgClient.request({
    method: 'DELETE',
    url: `/v3/suppression/bounces/${encodeURIComponent(email)}`
  });

  // DELETE returns 204 No Content on success
  return {
    content: [{
      type: 'text',
      text: response.statusCode === 204
        ? `Bounce removed. ${email} will receive future emails.`
        : `Unexpected status: ${response.statusCode}`
    }]
  };
});

Wiring /health/sendgrid via GET /scopes

GET /v3/scopes is the ideal SendGrid health probe — it validates that the API key is active, not revoked, and returns exactly which permissions the key has. This catches scope-reduced keys (e.g. when a key is edited to remove permissions) as well as fully revoked keys. Unlike most API health probes that just check connectivity, /scopes verifies that the key can actually perform the operations you need.

app.get('/health/sendgrid', async (req, res) => {
  try {
    const [response, body] = await sgClient.request({
      method: 'GET',
      url: '/v3/scopes'
    });

    const scopes = (body as { scopes: string[] }).scopes;
    const requiredScopes = ['mail.send', 'suppression.read'];
    const missingScopes = requiredScopes.filter(s => !scopes.includes(s));

    if (missingScopes.length > 0) {
      return res.status(503).json({
        status: 'degraded',
        error: `API key missing required scopes: ${missingScopes.join(', ')}`,
        granted_scopes: scopes
      });
    }

    return res.json({
      status: 'healthy',
      granted_scopes: scopes,
      has_mail_send: scopes.includes('mail.send'),
      has_suppression_read: scopes.includes('suppression.read'),
      has_suppression_delete: scopes.includes('suppression.delete')
    });
  } catch (err: any) {
    // SendGrid errors: err.response.status (HTTP) and err.response.body.errors[]
    return res.status(503).json({
      status: 'unhealthy',
      http_status: err.response?.statusCode ?? 503,
      errors: err.response?.body?.errors ?? [{ message: err.message }]
    });
  }
});

Frequently asked questions