Skip to content

[CON-3412] feat(sendgrid): New Provider Docs #678

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Fullstack-Hero wants to merge 6 commits into
base: main
Choose a base branch
from
Open

[CON-3412] feat(sendgrid): New Provider Docs #678

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3fb8279
Updated docs for metadata, read and write
Fullstack-Hero Jul 29, 2026
c2564b2
Remove delete action
Fullstack-Hero Jul 29, 2026
93d93b5
Fix table colums
Fullstack-Hero Jul 29, 2026
f919d53
Fix PR comments
Fullstack-Hero Aug 5, 2026
a7e85b6
Fix notes and limitations
Fullstack-Hero Aug 5, 2026
7758942
Remove a section
Fullstack-Hero Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 69 additions & 21 deletions src/provider-guides/sendGrid.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,86 @@
---
title: SendGrid
title: "SendGrid"
---

## What's supported

### Supported actions

This connector supports:
- [Read Actions](/read-actions), including full historic backfill for all supported objects below. Incremental read is not currently supported.
- [Write Actions](/write-actions) (create/update/delete).
- [Proxy Actions](/proxy-actions), using the base URL `https://api.sendgrid.com`.
- Subscribe Actions are not currently supported.

### Supported objects

export const Check = () => <span>✅</span>
export const Cross = () => <span>🚫</span>

<div style={{ width: '100%', overflowX: 'auto', display: 'block' }}>
<table style={{ width: '100%', minWidth: '100%', tableLayout: 'fixed', textAlign: 'center', borderCollapse: 'collapse', display: 'table' }}>
<thead style={{ display: 'table-header-group', width: '100%' }}>
<tr style={{ display: 'table-row', width: '100%' }}>
<th style={{ textAlign: 'left', width: '44%' }}>Object</th>
<th style={{ width: '14%' }}>Read</th>
<th style={{ width: '14%' }}>Write</th>
<th style={{ width: '14%' }}>Subscribe</th>
</tr>
</thead>
<tbody style={{ display: 'table-row-group', width: '100%' }}>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/contacts/get-sample-contacts">contacts</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/lists/get-all-lists">lists</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/segmenting-contacts/get-list-of-segments">segments</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/single-sends/get-all-single-sends">singlesends</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/templates-api/retrieve-all-templates">templates</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/custom-fields/get-all-field-definitions">field_definitions</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/sender-verification/get-all-verified-senders">verified_senders</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/sender-identities-api/get-all-senders">senders</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/bounces-api/retrieve-all-bounces">bounces</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/blocks-api/retrieve-all-blocks">blocks</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/spam-reports-api/retrieve-all-spam-reports">spam_reports</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/suppressions-global-suppressions/retrieve-all-global-suppressions">unsubscribes</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/invalid-emails-api/retrieve-all-invalid-emails">invalid_emails</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/suppressions-unsubscribe-groups/retrieve-all-suppression-groups">asm_groups</a></td><td><Check /></td><td><Check /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/categories/retrieve-all-categories">categories</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
<tr style={{ display: 'table-row' }}><td style={{ textAlign: 'left' }}><a href="https://www.twilio.com/docs/sendgrid/api-reference/subusers-api/list-all-subusers">subusers</a></td><td><Check /></td><td><Cross /></td><td><Cross /></td></tr>
</tbody>
</table>
</div>

### Example integration

To define an integration for SendGrid, create a manifest file that looks like this:
For an example manifest file of a SendGrid integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/sendGrid/amp.yaml).

```YAML
# amp.yaml
specVersion: 1.0.0
integrations:
- name: sendGrid-integration
displayName: My SendGrid Integration
provider: sendGrid
proxy:
enabled: true
```
## Before you get started

## Using the connector
To connect SendGrid with Ampersand, you will need a [SendGrid account](https://signup.sendgrid.com/).

This connector uses API Key auth, which means that you do not need to set up a Provider App before getting started. (Provider apps are only required for providers that use OAuth2 Authorization Code grant type.)
This connector uses **API key** authentication. You do **not** need to create a Provider App in Ampersand before getting started (Provider apps are only required for OAuth2 Authorization Code providers).

To start integrating with SendGrid:
- Create a manifest file like the example above.
- Deploy it using the [amp CLI](/cli/overview).
- Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for an API key.
- Start making [Proxy Calls](/proxy-actions), and Ampersand will automatically attach the API key supplied by the customer. Please note that this connector's base URL is `https://api.sendgrid.com`.
Each customer supplies their own SendGrid API key during installation via the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.

### Create a SendGrid API key

## Creating an API key for SendGrid
Follow SendGrid’s documentation to create an API key with the scopes your integration needs:

[Click here](https://www.twilio.com/docs/sendgrid) for more information about generating an API key for SendGrid. The UI components will display this link, so that your users can successfully create API keys.
1. Log in to your [SendGrid account](https://app.sendgrid.com/).
2. Go to **Settings → API Keys**.
3. Click **Create API Key**.
4. Choose **Restricted Access** and grant the minimum scopes required for your integration (for example, Marketing Campaigns for `lists`, Template Engine for `templates`, and Suppressions for `asm_groups` and suppression reads).
5. Copy the API key — SendGrid shows the full key only once.

SendGrid documentation: [Create and manage API keys](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys).

## Using the connector

To start integrating with SendGrid:

- Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/sendGrid/amp.yaml).
- Deploy it using the [amp CLI](/cli/overview).
- If you are using Read Actions, create a [destination](/destinations).
- Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component. The UI component will prompt the customer for their SendGrid API key.
- Start using the connector!
- If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
- If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
- If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls. Ampersand will automatically attach the customer's API key.
Loading