sendgrid

Health check — verifies the API key works and returns the scopes (permissions) granted to it. SendGrid: GET /v3/scopes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List your transactional email templates (Dynamic and/or Legacy). Returns { result: [...], _metadata } — use _metadata.next / page_token to paginate. SendGrid: GET /v3/templates.

{
  "type": "object",
  "properties": {
    "generations": {
      "default": "dynamic",
      "description": "Which template generation(s) to return (default: dynamic).",
      "type": "string",
      "enum": [
        "legacy",
        "dynamic",
        "legacy,dynamic"
      ]
    },
    "page_size": {
      "default": 50,
      "description": "Number of templates per page (1–200, default 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "page_token": {
      "description": "Pagination token from a previous response's _metadata.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a single transactional email template by id, including its versions (subject + content). SendGrid: GET /v3/templates/{template_id}.

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "The template id (dynamic template ids start with \"d-\")."
    }
  },
  "required": [
    "template_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List your Marketing Campaigns contact lists, each with its id, name, and contact_count. Returns { result: [...], _metadata }. SendGrid: GET /v3/marketing/lists.

{
  "type": "object",
  "properties": {
    "page_size": {
      "default": 100,
      "description": "Number of lists per page (1–1000, default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "page_token": {
      "description": "Pagination token from a previous response's _metadata.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get the total number of Marketing Campaigns contacts on your account. Returns { contact_count, billable_count }. SendGrid: GET /v3/marketing/contacts/count.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Look up marketing contacts by exact email address (a read-only lookup — mutates nothing). Returns { result: { "<email>": { contact: {...} } } }. SendGrid: POST /v3/marketing/contacts/search/emails.

{
  "type": "object",
  "properties": {
    "emails": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One or more exact email addresses to look up."
    }
  },
  "required": [
    "emails"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get global email statistics over a date range (delivered, opens, clicks, bounces, spam reports, etc.). Returns an array of { date, stats: [{ metrics: {...} }] }. SendGrid: GET /v3/stats.

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "description": "Start date in YYYY-MM-DD format (required)."
    },
    "end_date": {
      "description": "End date in YYYY-MM-DD format (defaults to today).",
      "type": "string"
    },
    "aggregated_by": {
      "description": "How to group the returned statistics.",
      "type": "string",
      "enum": [
        "day",
        "week",
        "month"
      ]
    },
    "limit": {
      "description": "Number of results to return.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "offset": {
      "description": "Number of results to skip (for pagination).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "start_date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List bounced email addresses (the bounce suppression list). Returns an array of { created, email, reason, status }. SendGrid: GET /v3/suppression/bounces.

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "Start of the time range, as a Unix timestamp (seconds).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "end_time": {
      "description": "End of the time range, as a Unix timestamp (seconds).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Number of bounces to return (1–500).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "description": "Number of bounces to skip (for pagination).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "email": {
      "description": "Filter to a specific bounced email address.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List globally-unsubscribed email addresses (the global suppression list). Returns an array of { created, email }. SendGrid: GET /v3/suppression/unsubscribes.

{
  "type": "object",
  "properties": {
    "start_time": {
      "description": "Start of the time range, as a Unix timestamp (seconds).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "end_time": {
      "description": "End of the time range, as a Unix timestamp (seconds).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Number of records to return.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "offset": {
      "description": "Number of records to skip (for pagination).",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

SENDS A REAL EMAIL immediately via SendGrid. Provide `from_email` and one or more `to` recipients, plus EITHER a subject + content OR a `template_id` (dynamic template ids start with "d-", pass values via dynamic_template_data). Returns { status: "accepted", message_id }. SendGrid: POST /v3/mail/send.

{
  "type": "object",
  "properties": {
    "from_email": {
      "type": "string",
      "description": "Sender email address (must be a verified sender/domain)."
    },
    "from_name": {
      "description": "Sender display name.",
      "type": "string"
    },
    "to": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One or more recipient email addresses."
    },
    "subject": {
      "description": "Email subject line. Required unless a template_id supplies it.",
      "type": "string"
    },
    "content_type": {
      "default": "text/html",
      "description": "MIME type of the body content (default text/html).",
      "type": "string",
      "enum": [
        "text/plain",
        "text/html"
      ]
    },
    "content": {
      "description": "The email body. Required unless template_id is provided.",
      "type": "string"
    },
    "template_id": {
      "description": "A template id to render (dynamic template ids start with \"d-\"). When set, `content` is omitted.",
      "type": "string"
    },
    "dynamic_template_data": {
      "description": "Key/value data merged into a dynamic template's handlebars variables.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "cc": {
      "description": "CC recipient email addresses.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "bcc": {
      "description": "BCC recipient email addresses.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "reply_to": {
      "description": "Reply-To email address.",
      "type": "string"
    }
  },
  "required": [
    "from_email",
    "to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

UPSERTS marketing contacts (creates new ones, updates existing ones by email) and optionally adds them to lists. This is an ASYNC job — returns { job_id } you can poll. SendGrid: PUT /v3/marketing/contacts.

{
  "type": "object",
  "properties": {
    "contacts": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Contact email address (required — the primary identifier for the contact)."
          },
          "first_name": {
            "description": "Contact first name.",
            "type": "string"
          },
          "last_name": {
            "description": "Contact last name.",
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "additionalProperties": {},
        "description": "A marketing contact. `email` is required; first_name/last_name are optional. Any additional keys are passed through as custom-field values (use the custom field's id or reserved name as the key)."
      },
      "description": "Contacts to add or update (each needs an `email`; custom fields pass through)."
    },
    "list_ids": {
      "description": "List ids to add these contacts to.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "contacts"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}