SendGrid publishes its OpenAPI spec at twilio/sendgrid-oai — but not as one file. It ships as 46 separate per-resource documents, so the first real step is merging them before any single-file generator will take it. SendGrid already ships official SDKs for Node, Python, C#, Java, PHP, Ruby, and Go, so this is for a language those don't cover, an internal wrapper, or agent tooling.
Where the spec lives
| Fact | Value |
|---|---|
| Repo | twilio/sendgrid-oai |
| Path | spec/yaml/ (also spec/json/) — 46 separate files, one per resource |
| Default branch | main |
| Spec version | OpenAPI 3.0 per file (e.g. tsg_mail_v3.yaml, tsg_stats_v3.yaml) |
| Combined size | ~1.6 MB across all 46 YAML files |
| License | MIT |
| Status | Repo README states "currently in Beta" |
Files are named tsg_<resource>_v3.yaml — tsg_mail_v3.yaml, tsg_stats_v3.yaml, tsg_webhooks_v3.yaml (the largest, at ~98 KB), and so on. There is no tsg_all_v3.yaml or similar bundle checked into the repo.
How to fetch it
Grab the whole spec/yaml/ directory with a shallow, sparse clone rather than 46 individual curl calls:
git clone --depth 1 --filter=blob:none --sparse \
https://github.com/twilio/sendgrid-oai.git
cd sendgrid-oai
git sparse-checkout set spec/yaml
Or pull the whole repo with gh repo clone twilio/sendgrid-oai if you want the JSON variants too.
The honest complication: there's no single spec to generate from
Every other spec in this series is one file you can point a generator at directly. SendGrid's isn't — it's 46 independently valid OpenAPI documents, each scoped to one resource (tsg_mail_v3.yaml for sending mail, tsg_stats_v3.yaml for stats, tsg_suppressions_v3.yaml for suppressions, and so on), confirmed by listing the directory:
ls spec/yaml/ | wc -l # 46
This means:
- You must merge them yourself before most single-file generators (
openapi-generator,openapi-typescript) will produce one coherent client. Apaths-and-componentsmerge script, or a tool likeopenapi-merge-cli, does this — watch for duplicatecomponents/schemasnames across files, since each was authored independently. - Or generate per-resource clients and compose them in your own wrapper — more calls, but no merge-conflict risk, and you only generate the resources you actually use.
- The repo is explicitly Beta. SendGrid's own README says the spec is "currently in Beta" and under active development — expect occasional drift between the spec and live API behavior, and check the repo's issues if a generated field looks wrong.
Notably, the README also says only the sendgrid-java helper library is currently auto-generated from this OAI spec — the other official SendGrid SDKs predate it and are maintained by hand.
Generate a TypeScript client locally
After merging (or per-resource):
npx openapi-merge-cli --config openapi-merge.json
npx @openapitools/openapi-generator-cli generate \
-i merged-sendgrid-openapi.yaml \
-g typescript-fetch \
-o ./generated/sendgrid-client
For a single resource without merging anything:
npx openapi-typescript spec/yaml/tsg_mail_v3.yaml -o ./src/sendgrid-mail.d.ts
Run whichever file you land on through the free OpenAPI validator — merged multi-file specs are exactly where duplicate-name and dangling-$ref errors show up.
The hosted path
Sourced takes SendGrid's per-resource files directly — connect the repo and point it at spec/yaml/, or upload the merged file — and produces hosted docs, a TypeScript SDK preview, a Python SDK preview, and an llms.txt file in one pass, with the multi-file merge already handled by the pipeline instead of a script you maintain. Previews are free and unlimited, with up to two hosted noindex docs sites and one hosted MCP server, no credit card required.
When this actually makes sense
- A language SendGrid doesn't officially cover — Rust, Kotlin, and other ecosystems have no official SendGrid SDK.
- Scoping a client to one resource. If you only send transactional mail, generating from
tsg_mail_v3.yamlalone avoids pulling in Marketing Campaigns, Stats, and SSO types you don't need. - Internal wrappers that need SendGrid's types without the opinions baked into the official libraries.
- Agent tooling. A generated client, or an MCP server built from the merged spec, gives an LLM agent typed tool calls against SendGrid.
If you're writing a Node, Python, C#, Java, PHP, Ruby, or Go app that sends mail through SendGrid, use the official library for that language. It's maintained by Twilio/SendGrid and already handles retry and rate-limit behavior — a generated client from a Beta spec won't match that out of the box.
FAQ
Does SendGrid have an official OpenAPI spec?
Yes. twilio/sendgrid-oai is Twilio/SendGrid's own repository, generated from their internal API spec source via the sendgrid-oas-transpiler. It's officially maintained, currently labeled Beta.
Why isn't there one file to download?
SendGrid ships the spec as 46 separate per-resource documents in spec/yaml/ and spec/json/ rather than a single bundle. You need to merge them (or generate per-resource) to get one client.
Is the SendGrid OpenAPI spec OpenAPI 3.0 or 3.1?
3.0, consistent across the per-resource files.
Which official SendGrid SDK is actually generated from this spec?
Only sendgrid-java, per the repo's README. The Node, Python, C#, PHP, Ruby, and Go libraries predate the OpenAPI spec and are maintained separately by hand.
Should I generate a client instead of using SendGrid's official SDK?
Not for Node, Python, C#, Java, PHP, Ruby, or Go — use the official library. Generate a client for an uncovered language, a single scoped resource, or agent tooling.
Can Sourced merge SendGrid's per-resource files automatically?
Yes — point Sourced at the spec/yaml/ directory (or your fork) and it handles the merge as part of generating hosted docs, TypeScript and Python SDK previews, and llms.txt. Previews are free and unlimited.