How to connect SendGrid to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect SendGrid from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

SendGrid tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every SendGrid call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

On SendGrid the 403 means the key is authentic but lacks the permission for the action, which is different from a 401 where the key itself is broken or mistyped. The taught causes, in the order search results give them: the key's scope is too narrow (fix: edit the key in SendGrid and switch to Full Access), the request is coming from outside the account's IP access management allowlist, or the account itself is suspended or against a billing or trial limit. A hosted connection fails these exactly like a manual one, because they are SendGrid account state, not connection state. The page's own cause remains the fourth one: a placeholder argument such as YOUR_ID reaching the API literally. Re-paste the current key, confirm the account status, then re-run with real arguments before assuming the connection is at fault.

Ask the agent to diagnose it:

Call sendgrid_get_a_user_s_account_information and tell me the account status, then quote the exact error text from the failed call. Do not retry the failed call yet.

SendGrid rate-limits different endpoints on different windows, and an agent that walks a contact list or message history one page at a time is the traffic shape that meets them. The fix is to narrow and pace the work: ask for a bounded page rather than a full export, use the statistics tools that aggregate instead of the per-record filters, and have the agent report the error's rate-limit detail rather than retry blindly. These limits are Twilio-side and documented in their docs; no reconnect changes them.

Ask the agent to diagnose it:

Tell me how many SendGrid calls you made in the last minute and what you were enumerating. Quote the exact error text and any rate-limit headers. Do not call SendGrid again until I reply.

Two failures share this symptom. If no SendGrid tools appear at all, the connection or pairing is incomplete: confirm the plugin was installed with --enable, that hermes clawlink begin and hermes clawlink finish both ran, and that SendGrid shows as connected in the dashboard. If most tools work and one name fails, the name is wrong rather than missing, and the error lists the closest real ones. There is also a first-call timing case: schemas load on demand, so the opening SendGrid call in a fresh session can arrive before the catalog and needs one retry. What does not apply is the usual advice for this symptom, which assumes a community MCP server missing from a client config file; there is no local server here.

Ask the agent to diagnose it:

List the SendGrid tools you actually have access to. If there are none, say so plainly and tell me whether SendGrid shows as connected. Do not guess tool names.

Double-check that the API key for SendGrid has the right scopes or account access. A valid key can still be too limited for some reads or writes.

Yes. ClawLink is the fastest way to connect Hermes to SendGrid: link your SendGrid account once in the browser and Hermes Agent can call the SendGrid API through 359 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect SendGrid in the dashboard and Hermes can use it from the next message — no config files, and the SendGrid key you paste is stored server-side instead of in your environment.

About two minutes. Sign in, click Connect next to SendGrid in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want SendGrid working from chat.

No, and that is the honest answer the AI Overviews give about this provider: SendGrid is send-only, with no inbound inbox and no reply threading. Reading replies belongs to an IMAP connection, which Hermes handles separately. This integration is the sending and marketing surface: mail, templates, campaigns, contacts, lists, and delivery analytics. If your loop depends on reading what people write back, pair this connection with the agent's email reading side rather than expecting SendGrid to cover it.

A SendGrid API key created in your SendGrid dashboard under Settings, API Keys, pasted once on the hosted setup page. Scope matters more here than on most providers: a restricted key fails specific classes of calls, and the fix search results teach is editing the key in SendGrid and switching it to Full Access. A 403 with a valid-looking connection is the classic shape of a scoped key meeting an endpoint its scope does not cover; a 401 is the key itself being wrong or regenerated. Because the key is stored server-side, rotating it in SendGrid means re-pasting the current key in one place.

The search-result safety framing warns against two things this setup avoids by construction: pasting keys into chat windows, and keys sitting in files on machines. Here the key goes into the hosted setup page once and is never exposed to the chat, and disconnecting SendGrid in the dashboard revokes the agent's use of it immediately. The remaining risk is reputational rather than credential-based: an agent that mass-sends from a warm domain can hurt deliverability, so send-triggering prompts deserve a confirmation step. Limited-scope keys are also worth considering if the account supports them, though Full Access is what most SendGrid integrations need.

The sending side and the marketing side: send mail and filter message history, manage contacts, lists, and custom fields, build and send campaigns, transactional templates, and single sends, manage sender identities and sender verification, read account information, IP pools and subusers, categories, automation and single-send statistics, and pull exported contact data. It is a large surface, and because SendGrid counts account objects rather than chat steps, the risk of a bad prompt is a badly built campaign or contact list, not a broken connection.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.