Update documentation to reflect use of promises.

[Berkmann18]

It's not an issue per se but more of a README/documentation suggestion.
That concerns the example(s) on the README/USE_CASES.

The basic example is this:

const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Sending with SendGrid is Fun',
  text: 'and easy to do anywhere, even with Node.js',
};
sgMail.send(msg);

But reading this makes me think it's a synchronous code which is fine but I didn't realise it was returning a Promise until running it live on Node v11.

I'm aware of the callback version:

sgMail
  .send(msg, (error, result) => {
    if (error) {
      //Do something with the error
    }
    else {
      //Celebrate
    }
  });

And that there's thenable use cases here and here that uses:

//...
sgMail
  .send(msg)
  .then(() => console.log('Mail sent successfully'))
  .catch(error => console.error(error.toString()));

But if someone runs an async code without rejection handling (so not using either try { await ... } catch (err) { ... } in ES8 or Promise.catch(...) in ES6) it can be noisy and possibly leave room for bugs and errors if someone were to use the package without a proper error handling mechanism.

So for example having this:

• ES6

const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Sending with SendGrid is Fun',
  text: 'and easy to do anywhere, even with Node.js',
};
sgMail
  .send(msg)
  .then(() => {}, console.error); //or .then(() => {}).catch(console.error)

• ES8

const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
const msg = {
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Sending with SendGrid is Fun',
  text: 'and easy to do anywhere, even with Node.js',
};

(async () => {
  try {
    await sgMail.send(msg);
  } catch (err) {
    console.error(err.toString());
  }
})();

Technical details:

• @sendgrid/[email protected]
• Node.js Version: 11.1.0

[thinkingserious]

Great idea @Berkmann18! Thanks for taking the time to make this suggestion.

I have labeled it appropriately to get this change integrated into our docs.

[Berkmann18]

@thinkingserious You're welcome.

[Sammy-White]

Thanks man this really helped me to fix an issue with my code.

Thanks a lot.

[Berkmann18]

@Sammy-White No problem, I'm glad I helped.

[ogrotten]

So I was digging around to see if this was promise-able or chainable. Nothing says it is, or even hints to it . . . and then I tripped across this issue.

It's quite a missed boat.

@Berkmann18 your doc suggestion is great. Thought about making a PR?

[Berkmann18]

@ogrotten Yup, see #877.