Sendgrid
Use this page to set up the Sendgrid source connector and find reference information.
Prerequisites
- A SendGrid account
- A SendGrid API Key with the required permissions
Setup guide
Step 1: Set up SendGrid
Create a SendGrid API Key with the permissions needed for the streams you want to sync. The connector uses the SendGrid v3 API.
The required API key scopes depend on the streams you enable:
| Streams | Required Scopes |
|---|---|
| Bounces, Blocks, Spam Reports, Invalid Emails, Global Suppressions | suppression.read or the specific suppression.{type}.read scopes |
| Suppression Groups, Suppression Group Members | asm.groups.read |
| Templates | templates.read |
| Contacts, Lists, Segments, Single Sends, Single Send Stats, Stats Automations, Campaigns | marketing.read |
For simplicity, create an API key with Full Access so all streams work correctly. For more granular permissions, enable only the scopes listed above for the streams you need.
Step 2: Set up the Sendgrid connector in Airbyte
- Log into your Airbyte Cloud account or go to the Airbyte Open Source dashboard.
- In the left navigation bar, click Sources. In the top-right corner, click + New source.
- On the Set up the source page, name the Sendgrid connector. Then select Sendgrid from the Source type dropdown.
- Enter your
api_key. - Enter your
start_date. - Click Set up source.
Supported sync modes
The Sendgrid source connector supports these sync modes:
Supported streams
- Blocks (Incremental)
- Bounces (Incremental)
- Campaigns
- Contacts
- Global Suppressions (Incremental)
- Invalid Emails (Incremental)
- Lists
- Segments
- Single Sends
- Single Send Stats
- Spam Reports (Incremental)
- Stats Automations
- Suppression Groups
- Suppression Group Members (Incremental)
- Templates
Create a read-only API key (Optional)
You can set up the SendGrid connector with any API key that has read permission. A dedicated read-only API key lets you control which resources Airbyte can read.
Give the API key read-only access to the resources you want to sync. For marketing streams (Contacts, Lists, Segments, Single Sends, Campaigns), it needs the marketing.read scope.
Limitations and troubleshooting
Expand to see details about Sendgrid connector limitations and troubleshooting.
Connector limitations
Rate limits
The standard Sendgrid requests limitation restrict the connector.
Troubleshooting
403 Forbidden errors
If you encounter 403 errors, check these points:
-
Verify API key permissions: Make sure your API key has the required scopes for the streams you’re syncing. See Setup guide for each stream’s required scopes.
-
Legacy vs. New Marketing Campaigns: This connector uses the New Marketing Campaigns API (
/v3/marketing/*), which requires themarketing.readscope. If your SendGrid account uses Legacy Marketing Campaigns, marketing stream syncs return 403 errors. Legacy Marketing Campaigns use different API endpoints and permission scopes (marketing_campaigns.read), which aren’t compatible with this connector. -
Account type limitations: Some SendGrid account types may not access every API endpoint. Check that your SendGrid plan includes the features you’re trying to sync.
IP allow list
If you use Airbyte Cloud and your organisation restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.3.51 | 2026-11-10 | 91697 | Update dependencies |
| 1.3.50 | 2026-11-03 | 90744 | Update dependencies |
| 1.3.49 | 2026-10-20 | 89397 | Update dependencies |
| 1.3.48 | 2026-10-13 | 88788 | Update dependencies |
| 1.3.47 | 2026-10-06 | 88032 | Update dependencies |
| 1.3.46 | 2026-09-29 | 87325 | Update dependencies |
| 1.3.45 | 2026-09-22 | 86780 | Update dependencies |
| 1.3.44 | 2026-09-15 | 86214 | Update dependencies |
| 1.3.43 | 2026-09-08 | 85642 | Update dependencies |
| 1.3.42 | 2026-08-18 | 84757 | Update dependencies |
| 1.3.41 | 2026-08-11 | 84110 | Update dependencies |
| 1.3.40 | 2026-08-04 | 83615 | Update dependencies |
| 1.3.39 | 2026-07-28 | 83102 | Update dependencies |
| 1.3.38 | 2026-07-21 | 82574 | Update dependencies |
| 1.3.37 | 2026-07-14 | 82007 | Update dependencies |
| 1.3.36 | 2026-06-30 | 81252 | Update dependencies |
| 1.3.35 | 2026-06-23 | 80649 | Update dependencies |
| 1.3.34 | 2026-06-16 | 80013 | Update dependencies |
| 1.3.33 | 2026-06-09 | 79501 | Update dependencies |
| 1.3.32 | 2026-06-02 | 78949 | Update dependencies |
| 1.3.31 | 2026-04-28 | 77509 | Update dependencies |
| 1.3.30 | 2026-04-25 | 77009 | Promoted release candidate to GA |
| 1.3.30-rc.1 | 2026-04-16 | 76407 | Increase HTTPAPIBudget rate limit from 50 to 70 req/s |
| 1.3.29 | 2026-04-21 | 75796 | Update dependencies |
| 1.3.28 | 2026-04-14 | 76335 | Promoted release candidate to GA |
| 1.3.28-rc.5 | 2026-04-13 | 74713 | Add HTTPAPIBudget rate limiting (Phase 2) with concurrency=6 |
| 1.3.28-rc.4 | 2026-04-12 | 74713 | Add concurrency_level for parallel stream processing (concurrency=6) |
| 1.3.27 | 2026-03-24 | 75331 | Update dependencies |
| 1.3.26 | 2026-02-24 | 73950 | Update dependencies |
| 1.3.25 | 2026-02-10 | 73157 | Update dependencies |
| 1.3.24 | 2026-02-03 | 72566 | Update dependencies |
| 1.3.23 | 2026-01-20 | 72099 | Update dependencies |
| 1.3.22 | 2026-01-14 | 71536 | Update dependencies |
| 1.3.21 | 2025-12-18 | 70736 | Update dependencies |
| 1.3.20 | 2025-11-25 | 69988 | Update dependencies |
| 1.3.19 | 2025-11-18 | 69685 | Update dependencies |
| 1.3.18 | 2025-10-29 | 68852 | Update dependencies |
| 1.3.17 | 2025-10-22 | 68591 | Add suggestedStreams |
| 1.3.16 | 2025-10-21 | 68410 | Update dependencies |
| 1.3.15 | 2025-10-14 | 67931 | Update dependencies |
| 1.3.14 | 2025-10-07 | 67227 | Update dependencies |
| 1.3.13 | 2025-09-30 | 66871 | Update dependencies |
| 1.3.12 | 2025-09-23 | 62286 | Update dependencies |
| 1.3.11 | 2025-09-15 | 66078 | Update to CDK v7 |
| 1.3.10 | 2025-06-21 | 61826 | Update dependencies |
| 1.3.9 | 2025-06-14 | 61314 | Update dependencies |
| 1.3.8 | 2025-05-25 | 60199 | Update dependencies |
| 1.3.7 | 2025-05-04 | 58982 | Update dependencies |
| 1.3.6 | 2025-04-19 | 58405 | Update dependencies |
| 1.3.5 | 2025-04-12 | 57952 | Update dependencies |
| 1.3.4 | 2025-04-05 | 57415 | Update dependencies |
| 1.3.3 | 2025-03-29 | 56746 | Update dependencies |
| 1.3.2 | 2025-03-22 | 55038 | Update dependencies |
| 1.3.1 | 2025-03-13 | 55744 | Increase max concurrent async job count to 2 |
| 1.3.0 | 2025-03-04 | 55185 | Update manifest for adapting changes with AsyncRetriever |
| 1.2.9 | 2025-02-23 | 54625 | Update dependencies |
| 1.2.8 | 2025-02-15 | 54013 | Update dependencies |
| 1.2.7 | 2025-02-08 | 53508 | Update dependencies |
| 1.2.6 | 2025-02-01 | 52995 | Update dependencies |
| 1.2.5 | 2025-01-25 | 52535 | Update dependencies |
| 1.2.4 | 2025-01-18 | 51892 | Update dependencies |
| 1.2.3 | 2025-01-11 | 48238 | Update dependencies |
| 1.2.2 | 2024-10-29 | 47836 | Update dependencies |
| 1.2.1 | 2024-10-28 | 47588 | Update dependencies |
| 1.2.0 | 2024-10-13 | 46870 | Migrate to Manifest-only |
| 1.1.5 | 2024-10-12 | 46781 | Update dependencies |
| 1.1.4 | 2024-10-05 | 46460 | Update dependencies |
| 1.1.3 | 2024-09-28 | 46105 | Update dependencies |
| 1.1.2 | 2024-09-21 | 45782 | Update dependencies |
| 1.1.1 | 2024-09-14 | 45525 | Update dependencies |
| 1.1.0 | 2024-09-11 | 45191 | Move Contacts stream to declarative async job |
| 1.0.18 | 2024-09-07 | 45239 | Update dependencies |
| 1.0.17 | 2024-08-31 | 44953 | Update dependencies |
| 1.0.16 | 2024-08-24 | 44753 | Update dependencies |
| 1.0.15 | 2024-08-17 | 44233 | Update dependencies |
| 1.0.14 | 2024-08-12 | 43751 | Update dependencies |
| 1.0.13 | 2024-08-10 | 43635 | Update dependencies |
| 1.0.12 | 2024-08-03 | 43269 | Update dependencies |
| 1.0.11 | 2024-07-27 | 42729 | Update dependencies |
| 1.0.10 | 2024-07-20 | 42310 | Update dependencies |
| 1.0.9 | 2024-07-13 | 41753 | Update dependencies |
| 1.0.8 | 2024-07-10 | 41531 | Update dependencies |
| 1.0.7 | 2024-07-09 | 41137 | Update dependencies |
| 1.0.6 | 2024-07-06 | 40898 | Update dependencies |
| 1.0.5 | 2024-06-25 | 40356 | Update dependencies |
| 1.0.4 | 2024-06-22 | 40155 | Update dependencies |
| 1.0.3 | 2024-06-06 | 39197 | [autopull] Upgrade base image to v1.2.2 |
| 1.0.2 | 2024-05-21 | 38478 | Update deprecated authenticator package |
| 1.0.1 | 2024-05-20 | 38264 | Replace AirbyteLogger with logging.Logger |
| 1.0.0 | 2024-04-15 | 35776 | Migration to low-code CDK. Breaking change that updates configuration keys, removes unsubscribe_groups stream, renames a stream to singlesend_stats, and adds the singlesends stream. |
| 0.5.0 | 2024-03-26 | 36455 | Unpin CDK version, add record counts to state messages |
| 0.4.3 | 2024-02-21 | 35343 | Handle uncompressed contacts downloads. |
| 0.4.2 | 2024-02-12 | 35181 | Manage dependencies with Poetry. |
| 0.4.1 | 2023-10-18 | 31543 | Base image migration: remove Dockerfile and use the python-connector-base image |
| 0.4.0 | 2023-05-19 | 23959 | Add unsubscribe_groupsstream |
| 0.3.1 | 2023-01-27 | 21939 | Fix contacts missing records; Remove Messages stream |
| 0.3.0 | 2023-01-25 | 21587 | Make sure spec works as expected in UI - make start_time parameter an ISO string instead of an integer interpreted as timestamp (breaking, update your existing connections and set the start_time parameter to ISO 8601 date time string in UTC) |
| 0.2.16 | 2022-11-02 | 18847 | Skip the stream on 400, 401 - authorization required with log message |
| 0.2.15 | 2022-10-19 | 18182 | Mark the sendgrid api key secret in the spec |
| 0.2.14 | 2022-09-07 | 16400 | Change Start Time config parameter to datetime string |
| 0.2.13 | 2022-08-29 | 16112 | Revert back to Python CDK |
| 0.2.12 | 2022-08-24 | 15911 | Bugfix to allowing reading schemas at runtime |
| 0.2.11 | 2022-08-19 | 15800 | Bugfix to allow reading sentry.yaml at runtime |
| 0.2.10 | 2022-08-17 | 15734 | Fix yaml based on the new schema validator |
| 0.2.9 | 2022-08-11 | 15257 | Migrate to config-based framework |
| 0.2.8 | 2022-06-07 | 13571 | Add Message stream |
| 0.2.7 | 2021-09-08 | 5910 | Add Single Sends Stats stream |
| 0.2.6 | 2021-07-19 | 4839 | Gracefully handle malformed responses from the API |