> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# SendGrid

> Client-mode REST API connector for a curated Twilio SendGrid v3 slice: mail/send (raw or dynamic templates), user profile smoke, and transactional template list/get

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Twilio SendGrid API v3](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST mail/send | `POST /mail/send` | Raw content and/or dynamic `template_id`; **202 Accepted** |
| GET user/profile (smoke) | `GET /user/profile` | API-key credential check |
| GET templates | `GET /templates` | `generations` + required `page_size` |
| GET templates/\{id} | `GET /templates/{template_id}` | Single transactional template |

Default `BASE_ADDRESS` is `https://api.sendgrid.com/v3`. Topics use `messaging/sendgrid/<object>/<verb>`.

> [!NOTE]
>
> All events send `Authorization: Bearer {api_key}`. Prefer Hub secret `SENDGRID_API_KEY`. Inbound Event Webhook (delivered / bounce / open) → MQTT is out of scope for this client-mode package. EU regional subusers may use `https://api.eu.sendgrid.com/v3`. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Twilio SendGrid API v3
# Auth: Bearer {value.json.api_key}
# BASE_ADDRESS: https://api.sendgrid.com/v3

DEFINE ROUTE SendGridRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.sendgrid.com/v3"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuserprofile
        WITH SOURCE_TOPIC "messaging/sendgrid/user/get-profile"
        WITH DESTINATION_TOPIC "messaging/sendgrid/user/get-profile/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/user/profile"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Sendmail
        WITH SOURCE_TOPIC "messaging/sendgrid/mail/send"
        WITH DESTINATION_TOPIC "messaging/sendgrid/mail/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mail/send"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Listtemplates
        WITH SOURCE_TOPIC "messaging/sendgrid/template/list"
        WITH DESTINATION_TOPIC "messaging/sendgrid/template/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/templates?generations={value.json.generations}&page_size={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Gettemplate
        WITH SOURCE_TOPIC "messaging/sendgrid/template/get"
        WITH DESTINATION_TOPIC "messaging/sendgrid/template/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/templates/{value.json.template_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuserprofile | GET | `/user/profile` | `messaging/sendgrid/user/get-profile` | `messaging/sendgrid/user/get-profile/response` |
| Sendmail | POST | `/mail/send` | `messaging/sendgrid/mail/send` | `messaging/sendgrid/mail/send/response` |
| Listtemplates | GET | `/templates` | `messaging/sendgrid/template/list` | `messaging/sendgrid/template/list/response` |
| Gettemplate | GET | `/templates/{template_id}` | `messaging/sendgrid/template/get` | `messaging/sendgrid/template/get/response` |

## Auth

1. Create an API key in the [SendGrid UI](https://app.sendgrid.com/settings/api_keys) with Mail Send (and preferably Template Engine Read) scopes. Use a verified sender identity for `from`.
2. Set connector `BASE_ADDRESS` to `https://api.sendgrid.com/v3` (or `https://api.eu.sendgrid.com/v3` for EU regional).
3. Pass `api_key` on the MQTT payload so `Authorization: Bearer {value.json.api_key}` resolves.
4. Store the key in Hub / `GET SECRET "SENDGRID_API_KEY"`. Never commit real credentials.
5. Successful `GET /user/profile` returns **HTTP 200**. `POST /mail/send` returns **202 Accepted**. `GET /templates` returns **200** with a paged `result` array.

## Example payloads

**getUserProfile:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY"
}
```

**sendMail (raw):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY",
  "personalizations": [
    {
      "to": [{"email": "ops@example.com"}]
    }
  ],
  "from": {"email": "alerts@your-verified-domain.com", "name": "Coreflux"},
  "subject": "Coreflux alarm: vibration above threshold — Zone A",
  "content": [
    {
      "type": "text/plain",
      "value": "RMS exceeded limit on Zone A"
    }
  ]
}
```

**sendMail (dynamic template):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY",
  "personalizations": [
    {
      "to": [{"email": "ops@example.com"}],
      "dynamic_template_data": {
        "zone": "A",
        "metric": "vibration_rms",
        "value": 12.4
      }
    }
  ],
  "from": {"email": "alerts@your-verified-domain.com"},
  "template_id": "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

**listTemplates:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY",
  "generations": "dynamic",
  "page_size": "10"
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy with `-addRoute` from `SendGridRestApi.lot` (not `hub-metadata.lot`).

## See also

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.