Updating docs

CONTRIBUTING.md

@@ -117,7 +117,7 @@ The interface to the SendGrid API.
 
 All PRs require passing tests before the PR will be reviewed.
 
-All test files are in the `[tests](https://github.com/sendgrid/sendgrid-nodejs/tree/v3beta/test)` directory.
+All test files are in the [`tests`](https://github.com/sendgrid/sendgrid-nodejs/tree/v3beta/test) directory.
 
 For the purposes of contributing to this repo, please update the [`test.js`](https://github.com/sendgrid/sendgrid-nodejs/tree/v3beta/test/test.js) file with unit tests as you modify the code.
 
@@ -134,11 +134,6 @@ Generally, we follow the style guidelines as suggested by the official language.
 
 Please run your code through [ESLint](http://eslint.org/) Standard style guide.
 
-### Directory Structure
-
-* `examples` for example calls
-* `test`, for all tests
-
 ## Creating a Pull Request<a name="creating_a_pull_request"></a>
 
 1. [Fork](https://help.github.com/fork-a-repo/) the project, clone your fork,

README.md

@@ -13,6 +13,49 @@ By using this endpoint, you accept that you may encounter bugs and that the endp
 
 # Installation
 
+## Environment Variables
+
+First, get your free SendGrid account [here](https://sendgrid.com/free?source=sendgrid-nodejs).
+
+Next, update your environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys).
+
+```bash
+echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
+echo "sendgrid.env" >> .gitignore
+source ./sendgrid.env
+```
+
+## TRYING OUT THE V3 BETA MAIL SEND
+
+```bash
+git clone -b v3beta --single-branch https://github.com/sendgrid/sendgrid-nodejs.git
+cd sendgrid-nodejs
+npm install
+```
+
+* Update the to and from [emails](https://github.com/sendgrid/sendgrid-nodejs/blob/v3beta/examples/helpers/mail/example.js#L4).
+
+```bash
+node examples/helpers/mail/example.js
+```
+
+## TRYING OUT THE V3 BETA WEB API
+
+```bash
+git clone -b v3beta --single-branch https://github.com/sendgrid/sendgrid-nodejs.git
+```
+
+* Check out the documentation for [Web API v3 endpoints](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html).
+* Review the corresponding [examples](https://github.com/sendgrid/sendgrid-nodejs/blob/v3beta/examples).
+
+```bash
+$ node examples/example.js
+```
+
+* Check out the documentation for [Web API v3 /mail/send/beta endpoint](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html).
+
+## Once we are out of v3 BETA, the following will apply
+
 The following recommended installation requires [npm](https://npmjs.org/). If you are unfamiliar with npm, see the [npm docs](https://npmjs.org/doc/). Npm comes installed with Node.js since node version 0.8.x therefore you likely already have it.
 
 Add the following to your `package.json` file:
@@ -46,27 +89,15 @@ npm install sendgrid
 - The SendGrid Service, starting at the [free level](https://sendgrid.com/free?source=sendgrid-nodejs)
 - [Nodejs-HTTP-Client](https://github.com/sendgrid/nodejs-http-client)
 
-## Environment Variables
-
-First, get your free SendGrid account [here](https://sendgrid.com/free?source=sendgrid-nodejs).
-
-Next, update your environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys).
-
-```bash
-echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
-echo "sendgrid.env" >> .gitignore
-source ./sendgrid.env
-```
-
 # Quick Start
 
 ## Hello Email
 
 ```javascript
   var helper = require('sendgrid-nodejs').helper
 
-  from_email = new helper.Email("dx@sendgrid.com")
-  to_email = new helper.Email("elmer.thomas@sendgrid.com")
+  from_email = new helper.Email("test@example.com")
+  to_email = new helper.Email("test@example.com")
   subject = "Hello World from the SendGrid Node.js Library"
   content = new helper.Content("text/plain", "some text here")
   mail = new helper.Mail(from_email, subject, to_email, content)

examples/helpers/mail/example.js

@@ -1,12 +1,12 @@
 function helloEmail(){
   var helper = require('../../../lib/helpers/mail/mail.js')
 
-  from_email = new helper.Email("dx@sendgrid.com")
-  to_email = new helper.Email("elmer.thomas@sendgrid.com")
+  from_email = new helper.Email("test@example.com")
+  to_email = new helper.Email("test@example.com")
   subject = "Hello World from the SendGrid Node.js Library"
   content = new helper.Content("text/plain", "some text here")
   mail = new helper.Mail(from_email, subject, to_email, content)
-  email = new helper.Email("elmer.thomas+add_second_email@sendgrid.com")
+  email = new helper.Email("test2@example.com")
   mail.personalizations[0].addTo(email)
 
   return mail.toJSON()
@@ -16,32 +16,32 @@ function kitchenSink(){
   var helper = require('../../../lib/helpers/mail/mail.js')
 
   mail = new helper.Mail()
-  email = new helper.Email("dx@sendgrid.com", "DX")
+  email = new helper.Email("test@example.com", "Example User")
   mail.setFrom(email)
 
   mail.setSubject("Hello World from the SendGrid Node.js Library")
 
   personalization = new helper.Personalization()
-  email = new helper.Email("elmer.thomas@sendgrid.com", "Elmer Thomas")
+  email = new helper.Email("test1@example.com", "Example User")
   personalization.addTo(email)
-  email = new helper.Email("elmer.thomas@gmail.com", "Elmer Thomas Personal")
+  email = new helper.Email("test2@example.com", "Example User")
   personalization.addTo(email)
-  email = new helper.Email("elmer.thomas+cc@sendgrid.com", "Elmer Thomas CC")
+  email = new helper.Email("test3@example.com", "Example User")
   personalization.addCc(email)
-  email = new helper.Email("elmer.thomas+cc@gmail.com", "Elmer Thomas Personal CC")
+  email = new helper.Email("test4@example.com", "Example User")
   personalization.addCc(email)
-  email = new helper.Email("elmer.thomas+bcc@sendgrid.com", "Elmer Thomas BCC")
+  email = new helper.Email("test5@example.com", "Example User")
   personalization.addBcc(email)
-  email = new helper.Email("elmer.thomas+bcc@gmail.com", "Elmer Thomas Personal BCC")
+  email = new helper.Email("test6@example.com", "Example User")
   personalization.addBcc(email)
   personalization.setSubject("Hello World from the Personalized SendGrid Node.js Library")
   header = new helper.Header("X-Test", "True")
   personalization.addHeader(header)
   header = new helper.Header("X-Test2", "False")
   personalization.addHeader(header)
-  substitution = new helper.Substitution("%name%", "Elmer")
+  substitution = new helper.Substitution("%name%", "Example User")
   personalization.addSubstitution(substitution)
-  substitution = new helper.Substitution("%city%", "Riverside")
+  substitution = new helper.Substitution("%city%", "Denver")
   personalization.addSubstitution(substitution)
   custom_arg = new helper.CustomArgs("timing", "morning")
   personalization.addCustomArg(custom_arg)
@@ -105,7 +105,7 @@ function kitchenSink(){
   mail.setIpPoolName("23")
 
   mail_settings = new helper.MailSettings()
-  bcc = new helper.Bcc(true, "elmer.thomas+spam@sendgrid.com")
+  bcc = new helper.Bcc(true, "test@example.com")
   mail_settings.setBcc(bcc)
   footer = new helper.Footer(true, "some footer text", "<html><body>some footer text</body></html>")
   mail_settings.setFooter(footer)
@@ -126,7 +126,7 @@ function kitchenSink(){
   tracking_settings.setGanalytics(ganalytics)
   mail.addTrackingSettings(tracking_settings)
 
-  email = new helper.Email("dx+reply@sendgrid.com", "DX")
+  email = new helper.Email("test@example.com", "Example User")
   mail.setReplyTo(email)
 
   return mail.toJSON()

test/helpers/mail/test.js

@@ -5,11 +5,11 @@ describe('helloEmail', function () {
   var helper = require('../../../lib/helpers/mail/mail.js')
 
   mail = new helper.Mail()
-  email = new helper.Email("dx@sendgrid.com")
+  email = new helper.Email("test@example.com")
   mail.setFrom(email)
 
   personalization = new helper.Personalization()
-  email = new helper.Email("elmer.thomas@sendgrid.com")
+  email = new helper.Email("test@example.com")
   personalization.addTo(email)
   mail.addPersonalization(personalization)
 
@@ -20,7 +20,7 @@ describe('helloEmail', function () {
   content = new helper.Content("text/html", "<html><body>some text here</body></html>")
   mail.addContent(content)
 
-  test_payload = '{"from":{"email":"dx@sendgrid.com"},"personalizations":[{"to":[{"email":"elmer.thomas@sendgrid.com"}]}],"subject":"Hello World from the SendGrid Node.js Library","content":[{"type":"text/plain","value":"some text here"},{"type":"text/html","value":"<html><body>some text here</body></html>"}]}'
+  test_payload = '{"from":{"email":"test@example.com"},"personalizations":[{"to":[{"email":"test@example.com"}]}],"subject":"Hello World from the SendGrid Node.js Library","content":[{"type":"text/plain","value":"some text here"},{"type":"text/html","value":"<html><body>some text here</body></html>"}]}'
 
   it('builds the correct payload', function() {
       assert.equal(JSON.stringify(mail.toJSON()), test_payload, 'payload is correct')
@@ -32,32 +32,32 @@ describe('kitchenSink', function () {
   var helper = require('../../../lib/helpers/mail/mail.js')
 
   mail = new helper.Mail()
-  email = new helper.Email("dx@sendgrid.com", "DX")
+  email = new helper.Email("test@example.com", "Example User")
   mail.setFrom(email)
 
   mail.setSubject("Hello World from the SendGrid Node.js Library")
 
   personalization = new helper.Personalization()
-  email = new helper.Email("elmer.thomas@sendgrid.com", "Elmer Thomas")
+  email = new helper.Email("test@example.com", "Example User")
   personalization.addTo(email)
-  email = new helper.Email("elmer.thomas@gmail.com", "Elmer Thomas Personal")
+  email = new helper.Email("test@example.com", "Example User")
   personalization.addTo(email)
-  email = new helper.Email("elmer.thomas+cc@sendgrid.com", "Elmer Thomas CC")
+  email = new helper.Email("test@example.com", "Example User")
   personalization.addCc(email)
-  email = new helper.Email("elmer.thomas+cc@gmail.com", "Elmer Thomas Personal CC")
+  email = new helper.Email("test@example.com", "Example User")
   personalization.addCc(email)
-  email = new helper.Email("elmer.thomas+bcc@sendgrid.com", "Elmer Thomas BCC")
+  email = new helper.Email("test@example.com", "Example User")
   personalization.addBcc(email)
-  email = new helper.Email("elmer.thomas+bcc@gmail.com", "Elmer Thomas Personal BCC")
+  email = new helper.Email("test@example.com", "Example User")
   personalization.addBcc(email)
   personalization.setSubject("Hello World from the Personalized SendGrid Node.js Library")
   header = new helper.Header("X-Test", "True")
   personalization.addHeader(header)
   header = new helper.Header("X-Test2", "False")
   personalization.addHeader(header)
-  substitution = new helper.Substitution("%name%", "Elmer")
+  substitution = new helper.Substitution("%name%", "Example User")
   personalization.addSubstitution(substitution)
-  substitution = new helper.Substitution("%city%", "Riverside")
+  substitution = new helper.Substitution("%city%", "Denver")
   personalization.addSubstitution(substitution)
   custom_arg = new helper.CustomArgs("timing", "morning")
   personalization.addCustomArg(custom_arg)
@@ -120,7 +120,7 @@ describe('kitchenSink', function () {
   mail.setIpPoolName("23")
 
   mail_settings = new helper.MailSettings()
-  bcc = new helper.BCC(true, "elmer.thomas+spam@sendgrid.com")
+  bcc = new helper.BCC(true, "test@example.com")
   mail_settings.setBcc(bcc)
   footer = new helper.Footer(true, "some footer text", "<html><body>some footer text</body></html>")
   mail_settings.setFooter(footer)
@@ -141,10 +141,10 @@ describe('kitchenSink', function () {
   tracking_settings.setGanalytics(ganalytics)
   mail.addTrackingSettings(tracking_settings)
 
-  email = new helper.Email("dx+reply@sendgrid.com", "DX")
+  email = new helper.Email("test@example.com", "Example User")
   mail.setReplyTo(email)
 
-  test_payload = '{"from":{"email":"dx@sendgrid.com","name":"DX"},"personalizations":[{"to":[{"email":"elmer.thomas@sendgrid.com","name":"Elmer Thomas"},{"email":"elmer.thomas@gmail.com","name":"Elmer Thomas Personal"}],"cc":[{"email":"elmer.thomas+cc@sendgrid.com","name":"Elmer Thomas CC"},{"email":"elmer.thomas+cc@gmail.com","name":"Elmer Thomas Personal CC"}],"bcc":[{"email":"elmer.thomas+bcc@sendgrid.com","name":"Elmer Thomas BCC"},{"email":"elmer.thomas+bcc@gmail.com","name":"Elmer Thomas Personal BCC"}],"subject":"Hello World from the Personalized SendGrid Node.js Library","headers":{"X-Test":"True","X-Test2":"False"},"substitutions":{"%name%":"Elmer","%city%":"Riverside"},"custom_args":{"timing":"morning","type":"marketing"},"send_at":1443636899}],"subject":"Hello World from the SendGrid Node.js Library","content":[{"type":"text/plain","value":"some text here"},{"type":"text/html","value":"<html><body>some text here</body></html>"},{"type":"text/calendar","value":"Party Time"}],"attachments":[{"content":"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3JhcyBwdW12","type":"application/pdf","filename":"balance_001.pdf","disposition":"attachment"},{"content":"BwdW","type":"image/png","filename":"banner.png","disposition":"inline","content_id":"banner"}],"template_id":"439b6d66-4408-4ead-83de-5c83c2ee313a","sections":{"%section1%":"Textforasubstitutiontagofsection1","%section2%":"Textforasubstitutiontagofsection2"},"headers":{"X-Test3":"1","X-Test4":"2"},"categories":["January","2015"],"custom_args":{"timing":"evening","type":"summer_contest"},"send_at":1443636899,"batch_id":"some_batch_id","asm":{"group_id":3,"groups_to_display":[1,4,5]},"ip_pool_name":"23","mail_settings":{"bcc":{"enable":true,"email":"elmer.thomas+spam@sendgrid.com"},"footer":{"enable":true,"text":"some footer text","html":"<html><body>some footer text</body></html>"},"sandbox_mode":{"enable":true},"spam_check":{"enable":true,"threshold":1,"post_to_url":"https://gotchya.example.com"}},"tracking_settings":{"click_tracking":{"enable":false,"enable_text":false},"open_tracking":{"enable":true,"substitution_tag":"Optional tag to replace with the open image in the body of the message"},"subscription_tracking":{"enable":true,"text":"text to insert into the text/plain portion of the message","html":"html to insert into the text/html portion of the message","substitution_tag":"Optional tag to replace with the open image in the body of the message"},"ganalytics":{"enable":true,"utm_source":"some utm source","utm_medium":"some utc medium","utm_term":"some utm term","utm_content":"some utm content","utm_campaign":"some utm campaign"}},"reply_to":{"email":"dx+reply@sendgrid.com","name":"DX"}}'
+  test_payload = '{"from":{"email":"test@example.com","name":"DX"},"personalizations":[{"to":[{"email":"test@example.com","name":"Example User"},{"email":"test@example.com","name":"Example User"}],"cc":[{"email":"test@example.com","name":"Example User"},{"email":"test@example.com","name":"Example User"}],"bcc":[{"email":"test@example.com","name":"Example User"},{"email":"test@example.com","name":"Example User"}],"subject":"Hello World from the Personalized SendGrid Node.js Library","headers":{"X-Test":"True","X-Test2":"False"},"substitutions":{"%name%":"Example User","%city%":"Denver"},"custom_args":{"timing":"morning","type":"marketing"},"send_at":1443636899}],"subject":"Hello World from the SendGrid Node.js Library","content":[{"type":"text/plain","value":"some text here"},{"type":"text/html","value":"<html><body>some text here</body></html>"},{"type":"text/calendar","value":"Party Time"}],"attachments":[{"content":"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3JhcyBwdW12","type":"application/pdf","filename":"balance_001.pdf","disposition":"attachment"},{"content":"BwdW","type":"image/png","filename":"banner.png","disposition":"inline","content_id":"banner"}],"template_id":"439b6d66-4408-4ead-83de-5c83c2ee313a","sections":{"%section1%":"Textforasubstitutiontagofsection1","%section2%":"Textforasubstitutiontagofsection2"},"headers":{"X-Test3":"1","X-Test4":"2"},"categories":["January","2015"],"custom_args":{"timing":"evening","type":"summer_contest"},"send_at":1443636899,"batch_id":"some_batch_id","asm":{"group_id":3,"groups_to_display":[1,4,5]},"ip_pool_name":"23","mail_settings":{"bcc":{"enable":true,"email":"test@example.com"},"footer":{"enable":true,"text":"some footer text","html":"<html><body>some footer text</body></html>"},"sandbox_mode":{"enable":true},"spam_check":{"enable":true,"threshold":1,"post_to_url":"https://gotchya.example.com"}},"tracking_settings":{"click_tracking":{"enable":false,"enable_text":false},"open_tracking":{"enable":true,"substitution_tag":"Optional tag to replace with the open image in the body of the message"},"subscription_tracking":{"enable":true,"text":"text to insert into the text/plain portion of the message","html":"html to insert into the text/html portion of the message","substitution_tag":"Optional tag to replace with the open image in the body of the message"},"ganalytics":{"enable":true,"utm_source":"some utm source","utm_medium":"some utc medium","utm_term":"some utm term","utm_content":"some utm content","utm_campaign":"some utm campaign"}},"reply_to":{"email":"test@example.com","name":"DX"}}'
 
   it('builds the correct payload', function() {
       assert.equal(JSON.stringify(mail.toJSON()), test_payload, 'payload is correct')