Rework the API To make it more Discoverable and easier to use.

[MycroftH]

Issue Summary

Rework the API to make it more discoverable and easier to use. SendGrid is normally amazing... but this API is very lacking. It's a very leaky abstraction of the API. An API should abstract as many of the implementation details as possible, while keeping flexibility up. While the current process is very flexible, it doesn't abstract any of the implementation details. Here's what I'd like to see the API look like:

var sg = new SendGridClient(myApiKey)
var mail = new Mail {
    From = new Email { Address = "[email protected]", Name = "Test User" },
    To = new Email { Address = "[email protected]", Name = "Test User" },
    Subject = "Test Message",
    Contents = {new Content { "text/plain", "Hello World!" }}
};
await sg.Send(mail);

.Send() should throw an exception if there's some kind of error. No dynamics. Everything is statically typed. Built on .Net 4.5 (yes, the older version, not everyone can upgrade to 4.5.2). The current API requires you know what too much about exactly how the transport works. You currently have to know what each of the possible status codes mean (There's roughly 45 of them. Have you documented what each of them do in the current API? Is 200 mean success? What about 201? If you say I should accept all 200's, is 206-PartialContent okay? Really none of this has to do with sending an email)

I'm sure some other people can add more to this, but I really think you should consider redesigning your API and focus on simplifying the caller's POV. You shouldn't be writing a REST client library. You're writing a wrapper around your services to make them easy to call.

A lot of these features are already in Jericho/sendgrid-csharp I think that customer so disliked your api that they wrote their own wrappers around it should say something.

[thinkingserious]

Hi @MycroftH,

Thanks for taking the time to provide your feedback! We are definitely on the same page.

If you want to continue to be a part of the evolution of this library, we have a great thread on this topic here, where I also explain the current state of this library and where we are headed: #303

Awesome changes are coming soon, we currently are planning the best way to collaborate with the community on this.

On that note, we would love your feedback on this: #317

Thanks again and we appreciate your support :)

[thinkingserious]

BTW, I added your vote to that ticket in our backlog to help bump it up our priority queue.