Update readme to include details about which API Key permissions are required

[jakejgordon]

Issue Summary

The readme is great overall. It does provide useful links to go and create the needed API key to use the client. However, it seems like there are a lot of confusing API key permissions that may or may not need to be configured on your API key to use this library (from what I can see in the sendgrid API key settings on the website). Some minor clarification of these permissions would be beneficial to new users (and users who are switching from the legacy username/password approach on version 6.* to the API key approach on version 9.*). At a minimum, maybe we could say something about the API key needing Mail Send = Full Access (assuming that is even true!) if you want to send emails? If I actually knew what was required myself I would happily just submit a pull request with the documentation change myself.

Thanks in advance!

[thinkingserious]

@ksigler7 is this something you can help with?

[thinkingserious]

Thanks for bringing this to our attention @jakejgordon!

[apigirl]

this docs page has more information about API key permissions: https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html

This docs page needs some tlc though and is high in our backlog for updates

[jakejgordon]

Thanks @ksigler7 -- I actually did attempt to read that documentation before I posted here. I think it is geared more toward if you're writing your own client to call the API. But for those who are just using a language-specific client that's already out there (like the C# one) to just send email, a quick note about "If you just want to send email, give your API Key {whatever permission is needed" would be just perfect in my mind. Anyway, it's not urgent and was just an idea. Thanks!

[thinkingserious]

Hi @jakejgordon,

Would you mind submitting a PR? If not, no worries, I'll leave this open for us to update. Thanks!

With Best Regards,

Elmer

[apigirl]

yeah, I think that's a really good idea to specify it in here! To finish your example sentence, it would be:
"To send email with your API key, make sure it has full mail send access:

{  
   "name":"My API Key",
   "scopes":[  
      "mail.batch.create",
      "mail.batch.delete",
      "mail.batch.read",
      "mail.batch.update",
      "mail.send"
   ],
   "sample":"data"
}

[jakejgordon]

Upon closer inspection, I think the disconnect for me was primarily between the existing documentation and what the screen actually looks like.

Here is what the documentation says under the "Add new General API Key":

In reality, this is what the API Key permissions page looks like to me right now in Chrome:

I honestly can't tell which access level I have selected.

Aside from that usability problem, I think the documentation in the readme should reference what the actual developer will have to configure in the web UI for managing keys on https://app.sendgrid.com/settings/api_keys. In other words, maybe it should say something like this:

To send email with your API key, make sure it has full mail send access. In [the API Keys settings page](https://app.sendgrid.com/settings/api_keys) you simply need to toggle the "Mail Send" permission to "Full Access". 

//--I think the below is something that is too technical or not pertinent from within the client (e.g. C# client) readme, but could be included if you wanted to call out that you can do this via the REST API as well:
To add permissions (scopes) to an existing key, you can do so by submitting a PUT request to [this endpoint](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/index.html#Update-the-name-amp-scopes-of-an-API-Key-PUT): 
{  
   "name":"My API Key",
   "scopes":[  
      "mail.batch.create",
      "mail.batch.delete",
      "mail.batch.read",
      "mail.batch.update",
      "mail.send"
   ],
   "sample":"data"
}

After taking the time to write this and poke around, I can see the total scope of the documentation you have to care about with all of the different clients and the generic docs. Basically, I'm not comfortable with making the documentation changes without having a better feel for how it plays into all of your other documentation. I'm not lazy, I just don't want to introduce any inconsistencies in your documentation pattern. Take it or leave it :)

And once again, thanks for a great product/client and documentation.

[childish-sambino]

This issue has been added to our internal backlog to be prioritized. Pull requests and +1s on the issue summary will help it move up the backlog.