OpenAPI SDK readiness
Twilio SendGrid Mail API OpenAPI spec score
Octri scored the public spec at https://raw.githubusercontent.com/twilio/sendgrid-oai/main/spec/json/tsg_mail_v3.json for what a code generator can do with it. This is a reading of the document, not a grade of the API.
3 operations · 6 models · 2 tags · OpenAPI 3.1.0
Scored 14 September 2026 · fingerprint 4ba24d0feb8a… · spec version 1.0.0 · server api.sendgrid.com
Unchanged since 14 September 2026.
Where the points went
Every rule, heaviest first, with what it cost this document and how much of the surface it touched. Open a row for the locations.
Successful responses declare a schema2.00.9 lost1 of 3 operations
Without a response schema every method returns `unknown`/`any`, so callers get no types and no autocompletion.
POST /v3/mail/send`SendMail` declares a success response with no schema, so the generated method returns an untyped value.
Shared models live in components and are $ref'd2.0Clean3 operations clean
Inline object schemas become anonymous per-operation types. The same model inlined in 20 operations generates 20 near-identical types instead of one.
Generated public names do not collide2.0Clean3 operations clean
When authored identifiers collapse to the same shared public name, the generator must silently rename one method; callers otherwise cannot predict the SDK surface from the spec.
Every path placeholder has a parameter1.5Clean3 operations clean
An undeclared `{id}` placeholder cannot become a typed method argument, so the generated request path is incomplete or uncompilable.
Every operation declares an operationId1.0Clean3 operations clean
Without one the generator synthesizes a name from the path, which changes whenever the path does. That is a silent breaking change for callers.
operationIds read as method names1.00.5 lost1 of 3 operations
The id becomes the method name. `ActionsActionsGet` generates `client.actions.actionsActionsGet()`; `getActions` generates `client.actions.get()`.
POST /v3/mail/send`SendMail` reads better as `createSendMail` at the call site.
Operations carry a summary or description1.0Clean3 operations clean
Operation prose becomes the method's doc comment, the text an IDE shows on hover.
Request bodies are documented1.0Clean3 operations clean
Body field descriptions become the doc comments on generated parameters; without them the SDK ships undocumented arguments.
Failure responses are declared1.0Clean3 operations clean
Declared error schemas become typed errors. Without them every failure surfaces as an untyped generic error.
Operations are tagged1.0Clean3 operations clean
Tags drive namespacing. Untagged operations fall back to a path segment, producing lopsided or `misc` namespaces.
No duplicate or equivalent paths1.0Clean3 paths clean
Paths differing only in parameter NAME are the same route to a server; the generated SDK ends up with two methods that call the same endpoint.
Authentication is described1.0CleanDeclared
Security schemes generate the SDK's auth configuration. A spec without them produces a client with no way to authenticate.
Parameters explain their purpose0.75Clean3 operations clean
Parameter descriptions become IDE hints on generated method arguments; bare names force SDK users back to the API reference.
A server URL is declared0.5CleanDeclared
Without a server URL the generated client must ship with an empty or placeholder base URL, adding setup work and easy production misconfiguration.
What 8.6 means for an SDK
A strong reading, and the three rules that decide most of it.
A generator has what it needs here: typed methods, named models and doc comments that say something. What is left is polish, and it can wait until after the first release.
Three rules carry six of the 10 points between them. On this document they took 0.93.
−0.9
Successful responses declare a schema
1 of 3 operations
Clean
Shared models live in components and are $ref'd
3 operations clean
Clean
Generated public names do not collide
3 operations clean
What to change first
Every rule that deducted, in the order they cost.
Successful responses declare a schema
Give the success response a schema, or a $ref to one in components. A 204 needs nothing. Inside Octri this one has a one-click fix.
operationIds read as method names
Name the id for the action, not the route. The audit suggests one per operation and can apply it. Inside Octri this one has a one-click fix.
The spec at raw.githubusercontent.comis public. Octri keeps the `info` block, the score, and up to five sample finding locations per rule. The document itself is not stored and is not served from here. The audit predicts what an SDK generator can do with the description; it is not a security review, an uptime measurement or a critique of the API’s design. This page is not affiliated with Twilio SendGrid Mail API or Twilio SendGrid Support.