npm package: @journeyapps-solutions/cc-sendgrid
Description: SendGrid MailService wrapper
Author: Anton Van Zyl
Latest version: 1.2.4

# cc-sendgrid

This is a wrapping class for sendgrid mailing.
This will enable Cloud Code to send a mail safely in the enviroment.

Mail Service wrapper for sendGrid
@see https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/mail

## Documentation
All code is clearly documented, please see code for more details.
View an example below.

## Installation

#### Per machine

```
# Once as setup
npm login
 > journeyapps-solutions-user
 > see password on 1Password
 > infrastructure+npmsolutions@journeyapps.com

yarn add @journeyapps-solutions/cc-sendgrid --save
```

#### Per CloudCode app

```
NPM_TOKEN=... # Token for journeyapps-solutions-user from 1Password
echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ./app/cloudcode/.npmrc
```

#### Per CloudCode task

```
yarn add @journeyapps-solutions/cc-sendgrid
```

## Deploying

```
yarn version
```

## Usage

#### Environment Variables
The send function will check the environment in which it is running by using the `config.env` variable passed in on the `send` function. Default environment is 'testing'.

Note:
* In testing it will only send mails to \*@journeyapps.com emails
* In staging it will only send mails to \*@journeyapps.com and whiteList emails.
* In production it will not filter any mails.

To add a whitelist email, see example below

Note:
* If no whitelist emails are added, the mail will be sent to any email address
* If there are whitelist emails, it will send to the listed emails and `*@journeyapps.com` on staging

#### Constructing a mail
cc-sendgrid is essentially a wrapper for the sendGrid node module. We add some validation and reporting. That being said, to construct a mail, you can directly follow the sendgrid documentation:

https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/helpers/classes/mail.js

or look at the examples from sendgrid:

https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/mail/USE_CASES.md


### Cloud Code:

config.js:

```js
// Credentials used
SENDGRID_API_KEY : '<SENDGRID_API_KEY>';

//cc-sendgrid configuration
email : {
    from: {
      name: 'Name of email action',
      email: 'no-reply@journeyapps.com'
    },
    reply_to: {
      name: 'Journey Support',
      email: 'some-support@journeyapps.com'
    },
    bcc: 'no-reply@journeyapps.com',
    subject: 'Hallo'
},

whiteList : ['client@client.com', 'admin@client.com']

```

index.js:

```js
// make sure config.js has the relevant credentials
const config = require('./config');
const ccSendGrid = require('@journeyapps-solutions/cc-sendgrid');

export async function run() {

    let _mailer = new ccSendGrid(config.email, config.SENDGRID_API_KEY, CloudCode.task.env, config.whiteList);

    let msg = {
      subject: 'Sending with cc-sendgrid is fun',
      text: 'and easy to do anywhere, even with Node.js',
      html: '<strong>and easy to do anywhere, even with Node.js</strong>',
    };

    try {
      await _mailer.send(msg);
      console.log("Message was sent");
    } catch ( error ){
      console.log("Message not sent");
      //Report to rollbar
    }

}
```

## Testing

To test the module tape is used. You will require a SENDGRID_API_KEY to enable the sending of the mail. https://my.1password.com/vaults/i4r6nxvhx6e4joc6u3uhs2p76a/allitems/73ojbrcd7flhihr7hskyxeas4q

Note: If you want to receive the actual mail, set the `sandbox_mode` to false in `cc-sendgrid.test.js`

```js

yarn test --SENDGRID_API_KEY="<Your SENDGRID_API_KEY>"
```