sendgrid/sendgrid-oai

SendGrid's Open API specification for the v3 API

This is an OpenAPI representation of the SendGrid v3 Web API.

If you have an interesting use case for these files or have a request, please create an issue.

Project Status

This repository contains several OpenAPI representations of the Twilio SendGrid API.

1. Existing specification files that have been available for an extended time.
2. An OpenAPI v3.1 file that represents the future of this repository.

Existing OpenAPI files

The following OpenAPI representations are available in this repository to support any existing projects that may rely on them.

Swagger v2

All Swagger v2 representations of the Twilio SendGrid API describe the entirety of the API in a single JSON or YAML file.

• oai.json
• oai.yaml
• oai_stoplight.json

OpenAPI v3

The OpenAPI v3 representation of the Twilio SendGrid API located in the file below describes the entirety of the SendGrid API in a single JSON file.

• oai_v3_stoplight.json

Though this file should not be relied on going forward, it was used as a starting point for the oas_v3.json file that will be maintained going forward.

Future development and support

OpenAPI v3.1 Beta status

The OpenAPI v3.1 spec defined in oas_v3.json is currently in Beta.

This specification file is usable but subject to change. It may not accurately represent all Twilio SendGrid API features at this time. For this reason, the existing Swagger v2 and OpenAPI v3 files will remain in this repository. In the event that we remove any OpenAPI files, Twilio SendGrid will communicate the changes in advance.

If you've identified a mismatch between Twilio SendGrid's API behavior and this specification, please open an issue.

OpenAPI v3.1 details

Linting

The oas_v3.json specification file and its linked files are linted using Spectral. You can find the Spectral version in this repository's package.json file.

File organization

The oas_v3.json file uses JSON Reference syntax and JSON Pointer syntax to construct the full specification from the definitions in the spec directory. The specification has been segmented this way to improve maintainability.

Each directory in the spec directory is organized to match the structure of the Twilio SendGrid API reference. This structure is subject to change without notice while the specification remains in Beta.

Contributions

The OpenAPI v3.1 specification is generated internally by Twilio SendGrid tooling. For this reason, we cannot accept Pull Requests against any of the future-facing files: oas_v3.json, all files in the /spec directory.

We do, however, welcome any Issues you report, and we will gladly add them to our internal backlog.

Announcements

• This project contains a Beta version of Twilio SendGrid's OpenAPI v3.1 specification as of Q1 2022. The spec may not be accurate at this stage; it is in active development.

All the updates to this project are documented in our CHANGELOG.

How to Contribute

We encourage contributions to our projects, please see our CONTRIBUTING guide for more details.

Quick links:

• Feature Request
• Bug Reports

About

sendgrid-oai is maintained and funded by Twilio SendGrid, Inc. The names and logos for sendgrid-oai are trademarks of Twilio SendGrid, Inc.

License

The MIT License (MIT)

sendgrid-oai's Issues

Update .md files for SEO-ness

We received an awesome PR for #hacktoberfest on our ruby library
We would love to see the same thing on the README in this repo as well.
Please replace the "-" with "_" in README, CONTRIBUTING, USE_CASES, USAGE files.

Thanks and happy Hacktoberfest!!

Create a PULL_REQUEST_TEMPLATE

Issue Summary

We would like to have a template for describing what has changed in the pull request being submitted.

Github docs on this

You can use this file as an example

incorrect domain validation_results key

Issue Summary

The validation_results key is incorrect when doing a domain validation.

{ id: 1,
  valid: true,
  validation_resuts: // <- should be validation_results
   { dkim1: { reason: null, valid: true },
     dkim2: { reason: null, valid: true },
     mail_cname:
      { reason:
         'Expected your MX record to be "mx.sendgrid.net" but found "example.com".',
        valid: false },
     spf: { reason: null, valid: true } } }

Steps to Reproduce

1. Run the spec with Prism
2. Make a POST request to /v3/whitelabel/domains/{domainId}/validate
3. Observe the returned response contains validation_resuts instead of validation_results(returned from SendGrid's V3 API endpoint)

Any other information you want to share that is relevant to the issue being reported. Especially, why do you consider this to be a bug? What do you expect to happen instead?

Technical details:

• sendgrid-oai Version: master (latest commit: [#b732df8])

The "updated_at " property has a trailing space

Issue Summary

The "updated_at " property has a trailing space.

Steps to Reproduce

Search for "updated_at "

Add/Update Badges on README

Similar to what was done on the SendGrid node README:

• put the logo at the top of the list
• Add License like so
• make sure the other badges are available like so:

![SendGrid Logo](https://uiux.s3.amazonaws.com/2016-logos/email-logo%402x.png)

For the following, make sure the correct repo is linked!
For email notifications, you can change the "nodejs" to the language of this repo (e.g. java, python, ruby, php, csharp, go, etc)

[![BuildStatus](https://travis-ci.org/sendgrid/sendgrid-nodejs.svg?branch=master)](https://travis-ci.org/sendgrid/sendgrid-nodejs)
[![Email Notifications Badge](https://dx.sendgrid.com/badge/nodejs)](https://dx.sendgrid.com/newsletter/nodejs)
[![npm](https://img.shields.io/npm/l/express.svg)]()
[![Twitter Follow](https://img.shields.io/twitter/follow/sendgrid.svg?style=social&label=Follow)](https://twitter.com/sendgrid)
[![GitHub contributors](https://img.shields.io/github/contributors/sendgrid/sendgrid-nodejs.svg)](https://github.com/sendgrid/sendgrid-nodejs/graphs/contributors)

Thank you and happy #Hacktoberfest!!

Update the license file to have the correct date range

This license file might have the wrong end year (2017). If this is the case, please make a PR that updates the year. If the year is correct, please close this issue!

Add a unittest to check the license.md file date range

The end year in the license file should be "this year" and this should be checked on every run of the tests. If the end year is no correct, fail the test.
example:

Copyright (c) 2012-2016 SendGrid, Inc.
It is 2017, so this should be:
Copyright (c) 2012-2017 SendGrid, Inc.
and the test should fail.
--done

The operation GET /templates/{template_id} response schema is missing html_content and plain_content

Regarding the operation GET /templates/{template_id} the response includes the html_content and plain_content but it is not on the schema.

Operation Schema

        "responses": {
          "201": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/transactional_template"
            },

And transactional_template schema is

    "transactional_template": {
      "title": "Transactional Templates: Template",
      "allOf": [
        {
          "$ref": "#/definitions/transactional-templates-template-lean"
        },

And transactional-templates-template-lean is using

        "versions": {
          "type": "array",
          "description": "The different versions of this transactional template.",
          "items": {
            "$ref": "#/definitions/transactional-templates-version-output-lean"
          }
        }

And the issue is that transactional-templates-version-output-lean does not include html_schema or plain_content.

Could this please be considered for fixing.

Add a Code Of Conduct

Add a file to the root of this repo called CODE_OF_CONDUCT.md, with the content from the same file in our docs repo.

Create first time contributor documentation

Issue Summary

Our open sourced documentation has a great first time contributor page that we wish to duplicate here.

Acceptance Criteria

• We have a file in the root directory called first-timers.md or similar that helps a first time contributor make their first PR (please use our CONTRIBUTOR.md file for inspiration as well as this page)
• We provide a link to tasks with the labels "difficulty: easy" and "status: help wanted" (example query) to all the repos listed here, please scroll to the bottom.

Add unittest to check for specific repo files

This repo should have the following list of files included:

• ./Docker or docker/Docker
• ./docker-compose.yml or ./docker/docker-compose.yml
• ./.env_sample
• ./.gitignore
• ./.travis.yml
• ./.codeclimate.yml
• ./CHANGELOG.md
• ./CODE_OF_CONDUCT.md
• ./CONTRIBUTING.md
• ./.github/ISSUE_TEMPLATE
• ./LICENSE.md
• ./.github/PULL_REQUEST_TEMPLATE
• ./README.md
• ./TROUBLESHOOTING.md
• ./USAGE.md
• ./USE_CASES.md

This PR is only asking for tests of the existence of these files, if the files do not exist when you run the tests - do not worry about the tests not passing. We will identify this and create a new PR for the issue.
Thank you!

Title reverted to autogenerated version

In #6 you change the title from DX - v3 - Officially Documented Only - DO NOT EDIT to SendGrid V3, but it was reverted in one of the latest commits.

Prism and version URLs

I am trying to use Prism as a mock server for testing. I am running it like so:

prism mock https://raw.githubusercontent.com/sendgrid/sendgrid-oai/main/oai_v3_stoplight.json

The issue is, the when I use the SendGrid PHP library to call it, it's expecting to see a url prefixed with v3, so I am getting errors:

post /v3/mail/send ✖  error     Request terminated with error: https://stoplight.io/prism/errors#NO_PATH_MATCHED_ERROR: Route not resolved, no path matched

Sorry if this is the wrong forum to ask this, wasn't sure if I should ask here or https://github.com/sendgrid/sendgrid-php.

Add Code Review to Contributing.md

• Add a "Code Reviews" section on CONTRIBUTING.md
• Put the following under the header:

If you can, please look at open PRs and review them. Give feedback and help us merge these PRs much faster! If you don't know how, Github has some great information on how to review a Pull Request.

• Link the header in the Contributing.md Table of Contents
• Add a link to the README.md file: Review Pull Requests under "Contributing Section"

Add our Developer Experience Engineer career opportunity to the README

Issue Summary

The role of Developer Experience Engineer just became available and we want to announce it in the README. Here is the copy:

If you're a software engineer who is passionate about #DeveloperExperience and/or #OpenSource, this is an incredible opportunity to join our #DX team as a Developer Experience Engineer and work with @thinkingserious and @aroach! Tell your friends :)

Acceptance Criteria

• The above announcement is added to the Announcements section of this README

Null is not supported by swagger spec

I tried http://petstore.swagger.io/?url=https://raw.githubusercontent.com/sendgrid/sendgrid-oai/master/oai.json
You can see that it fails because the def contains "null" types which is not supported by the OAI spec at the moment (see OAI/OpenAPI-Specification#229)

swagger.json fails schema validation

When trying to use swagger.json with an instance of swagger ui, I get the following error:

{
    "messages": [
        "attribute definitions.global:empty_request.properties is missing",
        "attribute definitions.global:id.properties is missing"
    ],
    "schemaValidationMessages": [
        {
            "domain": "validation",
            "instance": {
                "pointer": "/paths/~1api_keys/get/responses/200"
            },
            "keyword": "oneOf",
            "level": "error",
            "message": "instance failed to match exactly one schema (matched 0 out of 2)",
            "schema": {
                "loadingURI": "http://swagger.io/v2/schema.json#",
                "pointer": "/definitions/responseValue"
            }
        }
    ]
}

To reproduce, browse to the public swagger ui instance and copy in the rawgit url for swagger.json. An error message will appear on the bottom right of the screen.

Schemes in Swagger v2 representations

In all the Swagger v2 representations below, "http" is designated as "schemes".
https://github.com/sendgrid/sendgrid-oai#swagger-v2

However, I suppose the "schemes" should be "https", since every requests to http://api.sendgrid.com time out.
When I imported these Swagger v2 representations into Postman, it didn't work because of time-out.

Sorry if this is the wrong forum to ask this, I'd be appreciated your response.

send mail & substitutions

I'm not sure is the best place to post this bug; don't hesitate to move it or explain to me where put this post.

The problem come from https://api.sendgrid.com/api/mail.send.xml

For an unknown reason, sometimes, when we use substitution in order to send emails, the substitution doesn't work for one or many fields.

I have request and response contents, but it contains business stuff, so do you have an email in order to send you the POST request ?

Subject and content in mail send API should not be required

Issue Summary

Subject and Content are defined as required according to the following, but they should not be required if you specify the template ID.
https://github.com/sendgrid/sendgrid-oai/blob/main/oai.yaml#L321-L322

Create a Use Cases Directory

Due to the success we have seen from hacktoberfest, we are seeing more people create use cases. This is amazing!
We want to make sure that everyone can find them. Please help us to break up this file and make it easier to read and manage:

• Create a Use Cases Directory
• Put a README.md in this directory
• Make a file in the new directory for each individual Use Case from USE_CASES.md, copy the content to this file
• For each file you've created, link to it from the README you created
• Organize the links in the README by type
• Make sure the names of the files you created are related to the Use Case
  Thank you!

Add a .env_sample file

Our preference is that users have an environment file when using the SendGrid API, because it is less likely that someone would commit their credentials to github.

Please make a couple changes:

• make a .env_sample file that contains: export SENDGRID_API_KEY=''
• make (or add) a .gitignore file and include .env
• add instructions to the README file about how to copy .env_sample to .env and add the API Key

Parameter "{field_name}" should be renamed to "field_name" in contacts search endpoint

Issue Summary

The contact recipients search endpoint takes a query string parameter that is currently called {field_name}. This name appears to be invalid and cannot be used as an identifier name in most languages, breaking client proxy generation.

I believe the parameter name should be field_name instead.

sendgrid-oai/spec/paths/legacy_marketing_campaigns/contacts_api_recipients.json

Line 952 in 072cebe

"name": "{field_name}",

Swagger.json File for Sendgrid

Issue Summary

We are planning to integrate the Sendgrid with Salesforce using external services and named credentials. In the case of External Service in Salesforce, we will need to provide "Swagger File" or "Service Schema Relative URL" of Sendgrid API. We didn't find this file or URL in any Public documentation released by Sendgrid.

However, we found one unpublished swagger file for Sendgrid on one forum [https://app.swaggerhub.com/apis/yuki-teraoka/send-grid_v_3_api_documentation/3.0]. We would like to request an updated swagger.json file or please confirm if we can proceed with the file we found on the forum.

Auto-generate the CHANGELOG.md file upon release

Issue Summary

For every release, we currently hand craft a CHANGELOG.md update, now we would like to automate this process. Please see the existing CHANGELOG.md for formatting structure.

Acceptance Criteria

• A script, which when run, creates a CHANGELOG.md update based on any merged PRs since the last release.

Add a .codeclimate.yml file to this repo

It is possible to configure how CodeClimate looks at a repository.
These Docs explain how this is done. Please create an appropriate .codeclimate.yml for this repo. It should test the main language of the repo and run tests.

CONTRIBUTING.md broken link

Issue Summary

Issue template link is broken in CONTRIBUTING.md

Clicking on sample bug report template redirects to 404 page.

Steps to Reproduce

1. Go to CONTRIBUTING.md
2. Click on sample bug report template

Allow the usage of personalisation data on endpoint "/marketing/test/send_email"

Issue Summary

Currently the endpoint POST /v3/marketing/test/send_email does not accept any personalisation data in the request.
Since the whole point of the dynamic templates is to have personalised data coming from APIs, this endpoint cannot be used for actual realistic tests.
Additionally, since this is the only endpoint that allows you to explicitly use some template version (instead of defaulting to the active one), it makes super difficult to change production emails without having to duplicate templates all over the place.

This whole thing of "how to have stage/production version of the templates" is its own topic, but it would be great if the /marketing/test/send_email endpoint accepted a personalisation object so we can test the template with all the dynamic data it uses.

OpenAPI interoperability issues

Hey,

I appreciate the effort put into providing OpenAPI documents, so thank you very much for that 👍
Sadly, client generation tools like AutoRest or Visual Studio are currently enable to process them due to interoperability issues:

As mentioned here by people way more comfortable with OpenAPI than I am, most of these issues seem to come from the fact the SendGrid OpenAPI document contains invalid "type": "null" nodes.

"default":[], while valid, also seems to cause issues with AutoRest.

Are you aware of these issues and do you plan to release an updated document at some point?

Thanks!

Hacktoberfest: SendGrid Current Status

SendGrid DX team current status:

• Wow
• OMG
• THANK YOU

Hacktoberfest 2017 has completely blown us away. We have had over 900 pull requests from over 300 contributors all in the last 30 days. That is more PRs than we normally get in 2 years!
We are actively working to review, comment, and/or merge as many PRs as we possibly can as quickly as we can.

We are currently working on “intaking” all the PRs that have come in, oldest first (we have about 400 remaining to go through). We are making sure that each PR we review is one we have a chance of merging - there have been a couple spammy items that came through. Due to the massive influx of requests so far, @thinkingserious and @mbernier have been working nights and weekends all month just to keep up! We’re not even mad, this is amazing!

Hey, that’s great for you - but what about my shirt!

If you have signed the CLA before 11/1, but haven’t had a PR merged yet, do not despair! We know we are behind on even just commenting on every PR to show you that we received it (something we typically do). If you submitted a mergeable (non-spam, actually adds value to the project) PR during October 2017, we will grant access to this page to redeem your shirt, sticker, and hacker pin. Next year, we will be sure to communicate this information sooner. We are sorry for any confusion we have caused. We appreciate those of you who have reached out to find out what’s going on!

What can I do to help move things along?

Have you signed the CLA yet?
We can only merge items from contributors who signed the CLA

Can you help another contributor?
If you can identify potential problems, add suggestions, or even leave a comment with your review of another PR (Looks good to me! Or I approve this change), that would help us review those PRs much faster, making it easier to get to your PR.

Do you even write tests, friend?
If you see a place where we could have a test to validate a piece of functionality, add it in. We know We know! It’s just another PR we have to review and merge. You’re right, it is! However, the more tests we have, the earlier our CI tool can catch issues, saving us a review as well as back and forth time.

@Akhi1, @pushkyn, @thepriefy

Incorrect body parameters.

In one of latest updates you added following:

      parameters:
        - in: body
          name: body
          schema:
            type: 'null'

It looks like you tried to specify that body should be empty, but instead, it means you expect JSON null as payload.
If you want to specify that body param should be empty just omit body param.

OAS specification has multiple errors

Issue Summary

I'm not able to generate a REST client from your public available oas file found on github https://github.com/sendgrid/sendgrid-oai/blob/main/oai.json

Do you have a working copy available somewhere?

Steps to Reproduce

1. Download the specification: https://github.com/sendgrid/sendgrid-oai/blob/main/oai.json
2. Run Autorest --input-file=oai.json --output-folder=Output --csharp --namespace=My.Backend.Services

Code Snippet

Autorest --input-file=oai.json --output-folder=Output --csharp --namespace=My.Backend.Services

Exception/Log

ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /messages/{msg_id} > get > responses > 400)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:25352:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /contactdb/recipients/search > post > responses > 200)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:19977:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /contactdb/recipients/search > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:19920:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /marketing/contacts/search/emails > post > responses > 200)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:13599:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /marketing/contacts/imports > put > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:13246:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /marketing/contacts/search > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:13131:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /whitelabel/dns/email > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:8989:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /whitelabel/links/{id}/validate > post > responses > 200)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:7583:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /alerts > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:4930:5
ERROR: Schema violation: String is too short (0 chars), minimum 1 (info > version)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:4:2
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /messages/{msg_id} > get > responses > 400)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:25352:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /contactdb/recipients/search > post > responses > 200)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:19977:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /contactdb/recipients/search > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:19920:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /marketing/contacts/search/emails > post > responses > 200)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:13599:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /marketing/contacts/imports > put > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:13246:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /marketing/contacts/search > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:13131:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /whitelabel/dns/email > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:8989:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /whitelabel/links/{id}/validate > post > responses > 200)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:7583:5
ERROR: Schema violation: Data does not match any schemas from 'oneOf' (paths > /alerts > post > parameters > 0)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:4930:5
ERROR: Schema violation: String is too short (0 chars), minimum 1 (info > version)
    - file:///C:/Users/trt/Downloads/SendGrid/oai.json:4:2
Process() cancelled due to failure

Technical details:

• sendgrid-oai version: 1.6.0
• open version: ?

Object with empty property name

Reported by @sergey-tihon as APIs-guru/openapi-directory#56

Object with empty property name, see:
https://github.com/sendgrid/sendgrid-swagger/blob/master/swagger.yaml#L10583-L10584
You probably meant hash, to do this in JSON Schema you should use additionalProperties, see:
http://json-schema.org/latest/json-schema-validation.html#anchor64

Hi from APIs.guru :)

@thinkingserious Thank you for sharing Swagger spec for your API.

I working on open catalog of API specs, something like "Wikipedia for Web APIs".
Most important thing is that aggregate specs from different sources and expose them through it own API. This allows 3rd-party services to provide automatic integrations, see this list.
And more integration will come in future.

I really interested in engaging API owners in this initiative so if you have time I would love to hear feedback and ideas from you.
So if you have a couple of minutes please contact me in Skype(ivangon4arov) or Hangouts([email protected]).

This issue just so start a conversation, so you can close it at any moment.

[Question] Public swagger ui instance to access this API

Hi
I want to access the sendgrid API using swagger ui.
Do you know of a public swagger ui instance that can be used?

I tried using the public swagger.io instance and gave it your swagger.json file. However, swagger doesn't send the necessary header required to get access to the API

Authorization: Bearer API_KEY

Do you know of an instance of swagger ui that will send this header? Or do I need to modify the swagger ui code myself?

Thanks

Single Quote character in the data is no longer letting us send emails via the SendGrid API v3

Issue Summary

Hi All

Apologies if this seems too complicated or convoluted I'm just trying to give as much detail as possible, the crux of the problem is much simpler and is written at the bottom of the steps to reproduce.

We have devices out in the field that all use SendGrid to send emails with attachments. All of a sudden all the devices have stopped being able to send emails through SendGrid. There have not been any hardware/software changes on any of these, these were all previously working and then all of a sudden stopped.

We have been doing a lot of testing to find the issue and we seem to have found why the problem is happening but not the reason why, as we believe the problem to be on the SendGrid side of things.

The code is executing on an embedded hcs12 processor. The code is written in C++. We are calling the V3 Web API using the JSON structure format. We run a Bash file on an embedded Linux platform that populates the fields based on what the user enters in the GUI (the details are passed in as parameters to the scripts) and enters them into the JSON structure which is passed as part of a cUrl command within the script. I'll attach the details of all these below.

Steps to Reproduce

1. Create a file called email.content to pass as the data parameter to the curl command.
   The contents of "email.content" are as follows:

'{"personalizations": [{"to": [{"email": "'$EMAILTO'"}],"cc":[{"email":"'$EMAILCC'"}],"subject": "'$EMAILSUBJECT'"}],"from": {"email": "[email protected]"},"content": [{"type": "text/plain", "value": "'$EMAILBODY'"}],"attachments": [{"content": "'$BASE64FILE'", "type": "text/plain", "filename": "'$EMAILATTACHMENTNAME'"}]}'

2. Send a curl command (we are using v7.16.2) on a linux system (v2.6.35.3) with the following parameters:

'curl --insecure -s -i --request POST --url https://api.sendgrid.com/v3/mail/send --header 'Authorization: Bearer BEARER_ID_HERE' --header 'Content-Type: application/json' -o email.output --data @email.content'

The 6 parameters are populated by passing 6 arguments when calling the script.

This will generate an {"errors":[{"message":"Bad Request","field":null,"help":null}]} error and won't send.

This is what we have been using for a couple of years until it fell over on Monday this week. We have discovered that if we remove the " ' " (single quote) characters from the beginning and end of this JSON data in the email.content file, or remove the file as an input and replace it with the entire string (works with the ' characters at the beginning and end) everything is working again.

So I'm wondering if there has been an update on the SendGrid side that no longer accepts the wrapping " ' " characters in the data and if it can be fixed or not so that we don't have to update all our customers devices?

Thanks very much.

Code Snippet

As above

Exception/Log

The error we receive in the curl trace file when using the --trace-ascii curl-trace.txt parameter to curl.
0000: {"errors":[{"message":"Bad Request","field":null,"help":null}]}
== Info: Connection #0 to host api.sendgrid.com left intact
== Info: Closing connection #0
== Info: SSLv3, TLS alert, Client hello (1):
=> Send SSL data, 2 bytes (0x2)
0000: ..

The curl trace on a GOOD transfer (no ' character at the beginning and end):
012e:
=> Send data, 326 bytes (0x146)
0000: {"personalizations": [{"to": [{"email": "[email protected]
0040: o.uk"}],"cc":[{"email":"[email protected]"}],"subject":
0080: "test"}],"from": {"email": "[email protected]"},"content":
00c0: [{"type": "text/plain", "value": "Yo"}],"attachments": [{"conten
0100: t": "aGVsbG8h", "type": "text/plain", "filename": "test-sec1_A.p
0140: df"}]}

On a FAILED transfer ( ' character at the beginning and end):
=> Send data, 16384 bytes (0x4000)
0000: '{"personalizations":[{"to":[{"email":"[email protected].
0040: uk"}],"cc":[{"email":"[email protected]"}],"subject":"t
0080: est"}],"from":{"email":"[email protected]"},"content":[{"typ
00c0: e":"text/plain","value":"test2"}],"attachments":[{"content":"JVB
...

Technical details:

https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html

OAS v3 spec (`oas_v3.json`) is invalid

Issue Summary

When running oas_v3.json through swagger-parser there are a few validation issues. The biggest one is that the properties of the components object (e.g. parameters, responses, requestBodies, etc.) must have values that are maps of strings to objects or references. And actually in OAS 3.1.0 the schemas property looks like it must be a map of strings to objects, i.e. references aren't allowed. In your oas_v3.json the values of these properties are just reference objects. The relevant section of the OAS 3.1.0 spec is here: https://spec.openapis.org/oas/v3.1.0#componentsObject

Additionally tags has a duplicate entry with name "Segmenting Contacts".

I have manually fixed these issues locally and can submit a pull request, but if you have an automated system that generates the oas_v3.json file the it would naturally be better to fix these issues there at the source.

Question: Contribution to v3 API docs

Hey guys! While working on an issue elsewhere I found a few typos in the Stoplight API docs. If I bundle those up into a PR, can you easily merge them in? It looks like code commits to this repo are autogenerated from Stoplight, so I wanted to ask. If not, is there another way to submit changes?

Document new Git workflow in CHANGELOG.md

Issue Summary

We want to update our git workflow to function more like Gitflow. We need to update the CONTRIBUTING.md file and PULL_REQUEST_TEMPLATE to direct contributors to fork/branch off the development branch and to merge their PRs with the development branch. Once this issue is complete, we will be creating the development branch and making that branch the default. This is part of a larger strategy to execute releases for this SDK on a predictable cadence.

Acceptance Criteria

• Update CONTRIBUTING.md documentation, explaining the process of forking and branching off the development branch and submitting PRs agains the development branch.
• Update PULL_REQUEST_TEMPLATE with the same addition to the CONTRIBUTING.md documentation.

Add a USAGE.md file

Usage files are really nice when they exist in a repo, because it makes it really obvious where to look for information about how to use this tool. It can be frustrating when you expect this file to be there and it's not.
Please add a USAGE.md file, you can see an example of this
here

Please make sure you modify the file for this repo (hint: Most of this information should be in the README file)

Publish JSON spec

To make use of these files you have to checkout the files and use them as a dependency. This is better than nothing. However, at least for Python, there’s an openapi client that can ready in spec file and generate a client on the fly. There’s other discovery tools that can read the spec too.

"Duplicate parameter name found in the endpoint" errors on v3.1 definition (parameters 'list_id', 'segment_id', 'recipient_id')

Issue Summary

When running validation from ApiMatic, several 'duplicate parameter name' errors are thrown:

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Lists[3] > GET_contactdb-lists-list_id [GET, /v3/contactdb/lists/{list_id}] > Parameters[1] > list_id.
Duplicate Parameter Name: list_id
Endpoint Name: GET_contactdb-lists-list_id.

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Lists[4] > PATCH_contactdb-lists-list_id [PATCH, /v3/contactdb/lists/{list_id}] > Parameters[1] > list_id.
Duplicate Parameter Name: list_id
Endpoint Name: PATCH_contactdb-lists-list_id.

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Lists[6] > GET_contactdb-lists-list_id-recipients [GET, /v3/contactdb/lists/{list_id}/recipients] > Parameters[1] > list_id.
Duplicate Parameter Name: list_id
Endpoint Name: GET_contactdb-lists-list_id-recipients.

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Lists[9] > DELETE_contactdb-lists-list_id-recipients-recipient_id [DELETE, /v3/contactdb/lists/{list_id}/recipients/{recipient_id}] > Parameters[1] > list_id.
Duplicate Parameter Name: list_id
Endpoint Name: DELETE_contactdb-lists-list_id-recipients-recipient_id.

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Lists[9] > DELETE_contactdb-lists-list_id-recipients-recipient_id [DELETE, /v3/contactdb/lists/{list_id}/recipients/{recipient_id}] > Parameters[3] > recipient_id.
Duplicate Parameter Name: recipient_id
Endpoint Name: DELETE_contactdb-lists-list_id-recipients-recipient_id.

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Segments[2] > GET_contactdb-segments-segment_id [GET, /v3/contactdb/segments/{segment_id}] > Parameters[1] > segment_id.
Duplicate Parameter Name: segment_id
Endpoint Name: GET_contactdb-segments-segment_id.

Duplicate parameter name found in the endpoint. ([View Details](https://docs.apimatic.io/rulesets/apimatic-codegen-validation/unique-endpoint-parameter-name))
Source: API > Endpoints > Contacts API - Segments[3] > PATCH_contactdb-segments-segment_id [PATCH, /v3/contactdb/segments/{segment_id}] > Parameters[2] > segment_id.
Duplicate Parameter Name: segment_id
Endpoint Name: PATCH_contactdb-segments-segment_id.

All of these errors occur for parameters that are present both as a segment, as well as a query string parameter. For example, from https://raw.githubusercontent.com/sendgrid/sendgrid-oai/main/spec/paths/legacy_marketing_campaigns/contacts_api_lists.json

Notice the first "global" parameter called list_id used as a path value, and then, on the GET definition, there is another instance of parameter list_id, but now from the query area.

The exact same issue exists for the other errors above: a global segment parameter is redefined as a specific query parameter in the individual endpoints.

Here are the 2 places in the example above:

sendgrid-oai/spec/paths/legacy_marketing_campaigns/contacts_api_lists.json

Lines 265 to 272 in 072cebe

	{
	"name": "list_id",
	"in": "path",
	"required": true,
	"schema": {
	"type": "string"
	}
	}

sendgrid-oai/spec/paths/legacy_marketing_campaigns/contacts_api_lists.json

Lines 282 to 289 in 072cebe

	{
	"name": "list_id",
	"in": "query",
	"description": "The ID of the list to retrieve.",
	"schema": {
	"type": "integer"
	}
	},

These errors prevent us from loading the definition in ApiMatic and converting it to v3.0, which is a requirement for us since our client generation tool doesn't support v3.1 OpenAPI definition files.

Could this be fixed in the source, so that the same parameter name is not used across multiple areas?

Run our *.md documents in this repo through the Grammer.ly service and update

Issue Summary

We would like to get our English polished up throughout the repo.

Aceptance Criteria

• Every .md file in this repo has been run through the Grammer.ly service and updated accordingly

Auto-generate the release notes upon release

Issue Summary

For every release, we hand craft the release notes on GitHub, now we would like to automate this process. Please see the existing release notes for an example. The contents of the release notes are generated from the CHANGELOG.md file. Here is the documentation for updating the release notes via the GitHub API.

Acceptance Criteria

• A script, which when run, creates a release note update based on the last deployed release

/suppression/bounces/{email} endpoint has wrong query parameter name

Issue Summary

I'm using the Retool Sendgrid resource which uses the Sendgrid open API spec. It looks like the query parameter is named email in one place, but named email_address in another, which is throwing the error "Required parameter email is not provided" in Retool but due to the spec, I have to provide email_address not email.

(oai_stoplight) Mock server verification

Issue Summary

Hello!
I wanted to participate by helping with issue sendgrid/sendgrid-go#255
But one of the requirements there is to write a test, that will show example with error from /templates/{template_id}
But there is no such description there. Moreover, I am not sure that it's possible with current solution for mock server to validate request and choose between successful and unsuccessful results.

Is it possible for you to implement such verification ability to mock server? Or maybe it's already implemented, and I just didn't found it? (:

Thank you in advance.

Add an ISSUE_TEMPLATE to this repo

Please steal this from one of the other SendGrid repos and add it here

Invalid URL to sendgrid logo

In README you use the following URL to logo:
https://assets3.sendgrid.com/mkt/assets/logos_brands/small/sglogo_2015_blue-9c87423c2ff2ff393ebce1ab3bd018a4.png
Currently, it returns 404 error, but it still showed in README because Github uses proxy.
This is very important for me since I use this logo in my catalog.
It would be great if you host logo directly inside the repo.

Add a .travis.yml file - check OAI structure

If it is possible, please add a Travis check that will cause the "build" to fail if:

• the JSON object is not proper JSON
• the JSON object is not proper OAI (formerly swagger)

In the path /v3/contactdb/lists/{list_id}?list_id=xxx what is the difference between the two list_id?

Just reviewing your documentation, and swagger, and I do not understand why some operations have path parameters repeated as query parameters.

e.g.

What is the different? I noticed one is string and the other integer.