From 41721d4190af4d1d11c888252b143f80dea508ab Mon Sep 17 00:00:00 2001 From: Elmer Thomas Date: Mon, 25 Jul 2016 22:25:25 -0700 Subject: [PATCH] Version Bump v4.01: Added Troubleshooting section --- README.md | 4 ++ TROUBLESHOOTING.md | 111 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/README.md b/README.md index d34e836f..8903b40f 100644 --- a/README.md +++ b/README.md @@ -157,6 +157,10 @@ We encourage contribution to our libraries (you might even score some nifty swag - [Sign the CLA to Create a Pull Request](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md#cla) - [Improvements to the Codebase](https://github.com/sendgrid/sendgrid-ruby/tree/master/CONTRIBUTING.md#improvements_to_the_codebase) +# Troubleshooting + +Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-ruby/blob/master/TROUBLESHOOTING.md) for common library issues. + # About sendgrid-ruby is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com). diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 00000000..693e36ae --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,111 @@ +If you have a non-library SendGrid issue, please contact our [support team](https://support.sendgrid.com). + +If you can't find a solution below, please open an [issue](https://github.com/sendgrid/sendgrid-ruby/issues). + + +## Table of Contents + +* [Migrating from v2 to v3](#migrating) +* [Continue Using v2](#v2) +* [Testing v3 /mail/send Calls Directly](#testing) +* [Error Messages](#error) +* [Versions](#versions) +* [Environment Variables and Your SendGrid API Key](#environment) +* [Using the Package Manager](#package-manager) + + +## Migrating from v2 to v3 + +Please review [our guide](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html) on how to migrate from v2 to v3. + + +## Continue Using v2 + +[Here](https://github.com/sendgrid/sendgrid-ruby/tree/0fbf579c0f7ed1dff87adc4957c4dc5a6b257068) is the last working version with v2 support. + +Using rubygems: + +Add this line to your application's Gemfile: + +```bash +gem 'sendgrid-ruby', '1.1.6' +``` + +And then execute: + +```bash +bundle +``` + +Or install it yourself using: + +```bash +gem install sendgrid-ruby -v 1.1.6 +``` + +Download: + +Click the "Clone or download" green button in [GitHub](https://github.com/sendgrid/sendgrid-ruby/tree/0fbf579c0f7ed1dff87adc4957c4dc5a6b257068) and choose download. + + +## Testing v3 /mail/send Calls Directly + +[Here](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/curl_examples.html) are some cURL examples for common use cases. + + +## Error Messages + +To read the error message returned by SendGrid's API: + +```ruby +begin + response = sg.client.mail._("send").post(request_body: mail.to_json) +rescue Exception => e + puts e.message +end +``` + + +## Versions + +We follow the MAJOR.MINOR.PATCH versioning scheme as described by [SemVer.org](http://semver.org). Therefore, we recommend that you always pin (or vendor) the particular version you are working with to your code and never auto-update to the latest version. Especially when there is a MAJOR point release, since that is guarenteed to be a breaking change. Changes are documented in the [CHANGELOG](https://github.com/sendgrid/sendgrid-ruby/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-ruby/releases) section. + + +## Environment Variables and Your SendGrid API Key + +All of our examples assume you are using [environment variables](https://github.com/sendgrid/sendgrid-ruby#setup-environment-variables) to hold your SendGrid API key. + +If you choose to add your SendGrid API key directly (not recommended): + +`sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])` + +becomes + +`sg = SendGrid::API.new(api_key: 'SENDGRID_API_KEY')` + +In the first case SENDGRID_API_KEY is in reference to the name of the environment variable, while the second case references the actual SendGrid API Key. + + +## Using the Package Manager + +We upload this library to [RubyGems](https://rubygems.org/gems/sendgrid-ruby) whenever we make a release. This allows you to use [RubyGems](https://rubygems.org) for easy installation. + +In most cases we recommend you download the latest version of the library, but if you need a different version, please use: + +Add this line to your application's Gemfile: + +```bash +gem 'sendgrid-ruby', 'X.X.X' +``` + +And then execute: + +```bash +bundle +``` + +Or install it yourself using: + +```bash +gem install sendgrid-ruby -v X.X.X +```