Connect SendGrid to Qoren with a restricted key

Connect SendGrid once with a restricted API key and your agents can wake when an email bounces, is dropped, is marked as spam or someone unsubscribes. Qoren sets up the SendGrid event webhook itself and switches on its signing, so there is nothing to copy. Agents you give access to can also check why SendGrid will not send to an address, look up recent email activity, and propose a fix for you to approve.

The key stays with Qoren and never reaches an agent's machine. For how connections work in general, see connect your tools with Integrations.

Before you start#

• You are the owner of your Qoren organization. Only the owner connects tools, gives agents access and disconnects.
• You can create API keys in your SendGrid account.
• Your SendGrid plan has a free event webhook slot, if you want triggers. SendGrid limits how many event webhooks each plan may have switched on, and Qoren never takes over one of yours.
• Integrations is on for your account. It is still rolling out: if your sidebar has no Integrations under Capabilities, it is not on your account yet.

Make the key#

SendGrid keys can be restricted permission by permission, and SendGrid tells Qoren exactly which ones a key has. Give it the least it needs.

1. In SendGrid, open Settings, then API Keys, choose Create API Key, name it Qoren and pick Restricted Access.
2. Give Event Webhook full access. Qoren needs to read and change event webhook settings to set up triggers.
3. Give read access to what your agents should see. Stats lets Qoren estimate how often an event happens, and Suppressions lets agents check why an address gets no email.
4. Give Mail Send only if agents should send email, and full access to Suppressions only if agents should take an address off a suppression list. Both always wait for your approval anyway.
5. Leave everything else at No Access, create the key and copy it. It starts with SG., and SendGrid shows it only once.

Connect it in Qoren#

1. In the sidebar, under Capabilities, click Integrations.
2. Under Add a tool, click SendGrid. The Connect SendGrid dialog shows the same steps as above.
3. If your account works for clients, choose who it is for under Which client is this for?. A client's connection can only be used by that client's agents.
4. Paste the key into API key.
5. Click Check key. Key checked shows the account (your SendGrid username), whether it can read and write, and Can add webhooks (N of M left), where M is what your plan allows.
6. Under What agents may do, choose Read only or Read and write.
7. Click Connect.

Screenshots of the dialog are in connect a tool.

What Qoren checks#

• That SendGrid accepts the key, and exactly what it may do, by asking SendGrid for the key's own permissions. The key can read when it has any read permission, and can write when it has Mail Send or any permission that creates, changes or deletes.
• Your region. Qoren asks SendGrid's main API first and its EU API second, so a key for an EU regional account works, and every later call goes to the same region.
• Event webhooks. Without Event Webhook full access the check says the key cannot change event webhook settings, and triggers need a better key. With it, Qoren reads how many event webhooks your plan allows from SendGrid itself, and how many are on. If all are in use, the check says so.
• Which account it is, from the account's username. If the key cannot read it, the check says so: then Qoren cannot confirm that a replacement key is for the same account.

Give an agent access#

No agent can use the connection until you give it access. Open the connection under Connected, pick the agent in Give access to…, choose its level and click Give access. See give an agent access.

Events#

To have one of these wake an agent, open the agent's Triggers tab and add it under From your connected tools. See wake an agent from a connected tool. Accepted, delivered and opened happen for nearly every email, so for most accounts they are busy: a digest suits them. When you pick an event, Qoren estimates how often it happens from SendGrid's daily stats for the last 30 days (that needs Stats read access; group unsubscribes have no estimate).

How the webhook is set up. Plans allow only a few event webhooks, so Qoren registers one per connection, named Qoren, for every event type, when you add the first trigger, and sends each event on to the triggers that want it. It then switches on signed delivery and keeps SendGrid's public key to check every delivery, refusing any with a timestamp older than five minutes. If signing cannot be switched on, Qoren deletes the webhook again rather than leave one it cannot check.

What the agent receives. SendGrid sends events in batches. Qoren splits each batch into single events, so each one goes through the trigger's delivery mode, conditions and hourly limit on its own, and recognises a retried event by its SendGrid event id. The agent gets the event's details: the address, the time, the reason or response, the message id, categories and the like. It is labelled as data from outside; see how events reach the agent.

Tools agents can use#

• Check email activity needs SendGrid's Email Activity history, a paid SendGrid add-on, and a key that may read it. Without it the tool tells the agent so, and nothing else is affected.
• Remove a suppression always asks because it lets email reach someone who bounced, complained or unsubscribed. That is a consent decision, and sending to them again can hurt your sender reputation.
• Send an email always asks, and sends to one recipient at a time. It is also an outbound tool: after an agent reads data from any connection, its outbound sends keep asking for 30 minutes, see outbound sends after a read.

Both writes wait on the Approvals page with the exact arguments, whatever the agent's autonomy says.

Limits and gotchas#

• Event webhooks per plan. The number of event webhooks you may have switched on depends on your SendGrid plan. Qoren reads SendGrid's own figure (max_allowed) instead of guessing, uses one slot per connection, and never switches off or replaces yours. If no slot is free, adding a trigger fails with a plain message: switch off or delete one you no longer use under Settings, Mail Settings, Event Webhooks, then try again.
• EU accounts. A key for an EU regional account only works on SendGrid's EU API. Qoren finds that out at the check and stays on it.
• Retries. SendGrid retries a delivery that fails for up to 24 hours. Qoren's daily check also turns its webhook back on if someone switched it or some of its event types off, points it back at Qoren, turns signing back on, or creates it again if it was deleted.

Troubleshooting#

• "SendGrid did not accept this key." It was deleted or not copied in full. Create a new key.
• The check says the key cannot change Event Webhook settings. Edit the key in SendGrid and give Event Webhook full access, then click Check key again.
• "Your SendGrid plan allows N event webhooks and all are in use." Free a slot in SendGrid, then add the trigger again.
• Replace key says Qoren cannot confirm it is the same account. The new key cannot read the account's username. Give it that access, or connect it as a new connection.
• The connection says Needs a new key or Needs attention. Its triggers are paused and you got an email. Replace the key, or fix the webhook and click Check again. See when a connected tool stops working.

Disconnect and delete the key#

1. Open the connection under Connected and click Disconnect.
2. In Disconnect SendGrid?, click Disconnect (or Keep it to back out).

Qoren deletes the stored key, removes the event webhook it registered, removes every agent's access and pauses the triggers that used SendGrid. It cannot revoke the key at SendGrid, so do that too: in SendGrid, open Settings, API Keys and delete the key.