Merge pull request #187 from sendgrid/tb-ccwebapi

Change to param to use Web API instead of X-SMTPAPI header

.travis.yml

@@ -5,14 +5,14 @@ node_js:
 - "0.12"
 - "iojs"
 before_install:
-- npm install -g npm@next
+- npm install -g npm@2
 notifications:
   hipchat:
     rooms:
       secure: UVH1YNXLzilBEQQblcNrkqIDn36OdSpVjAPJGiSnjox04Ze+PO6T3KZqAwoR/ODYu0ujR4aRrJ/84/OR3U+VorzqcNWodiVXPxR7jgG9BuFH5/XXDB0nTj4MVS5aCivwPuBQB3asNHOogQ4EWLZVw80XIw2pov5GEl1Pc9lN+CE=
     template:
     - '<a href="https://travis-ci.org/%{repository}/builds/%{build_id}">%{repository}
       Build %{build_number}</a> on branch <i>%{branch}</i> by %{author}: <strong>%{message}</strong>
-      <a href="https://github.com/sendgrid/docs/commits/%{commit}">View on GitHub</a>'
+      <a href="https://github.com/%{repository}/commits/%{commit}">View on GitHub</a>'
     format: html
     notify: true

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [2.0.0] - 
+## Fixed
+- Add cc now uses the WebAPI instead of the SMTPApi. Read disclaimer for details
+
 ## [1.9.1] - 2015-7-20
 ### Changed
 - Pinned request version to be less than `2.59.0` because it broke something

README.md

@@ -5,6 +5,20 @@ This nodejs module allows you to quickly and easily send emails through SendGrid
 [![BuildStatus](https://travis-ci.org/sendgrid/sendgrid-nodejs.svg?branch=master)](https://travis-ci.org/sendgrid/sendgrid-nodejs)
 [![NPM version](https://badge.fury.io/js/sendgrid.svg)](http://badge.fury.io/js/sendgrid)
 
+WARNING: This module was recently upgraded from [1.9.x](https://github.com/sendgrid/sendgrid-nodejs/tree/v1.9.1) to 2.X. There were API breaking changes for various method names. See [usage](https://github.com/sendgrid/sendgrid-nodejs#usage) for up to date method names.
+
+## PLEASE READ THIS
+
+**TLDR: If you upgrade and don't change your code appropriately, things *WILL* break.**
+
+One of the most notable changes is how addTo() behaves. We are now using our Web API parameters instead of the X-SMTPAPI header. What this means is that if you call addTo() multiple times for an email, ONE email will be sent with each email address visible to everyone. To utilize the original behavior of having an individual personalized email sent to each recipient you must now use addSmtpapiTo(). This will break substitutions if there is more than one To address added unless you update to use addSmtpapiTo().
+
+Smtpapi addressing methods cannot be mixed with non Smtpapi addressing methods. Meaning you cannot currently use Cc and Bcc with addSmtpapiTo().
+
+The send() method now raises a \SendGrid\Exception by default if the response code is not 200 and returns an instance of \SendGrid\Response.
+
+## Sample
+
 ```javascript
 var sendgrid  = require('sendgrid')(sendgrid_api_key);
 sendgrid.send({
@@ -161,23 +175,42 @@ email.subject = "This is a subject";
 
 You can add one or multiple TO addresses using `addTo`.
 
+**Note**: One of the most notable changes is how `addTo()` behaves. We are now using our Web API parameters instead of the X-SMTPAPI header. What this means is that if you call `addTo()` multiple times for an email, **ONE** email will be sent with each email address visible to everyone. In oder to use the header, please call the `addSmtpapiTo()` method.
+
 ```javascript
 var email     = new sendgrid.Email(); 
 email.addTo('[email protected]');
 email.addTo('[email protected]');
 sendgrid.send(email, function(err, json) { });
 ```
 
-NOTE: This is different than setting an array on `to`. The array on `to` will show everyone the to addresses it was sent to. Using addTo will not. Usually, you'll want to use `addTo`.  
+#### addSmtpapiTo
+
+
+```javascript
+var email = new sendgrid.Email()
+email.addSmtpapiTo('[email protected]');
+sendgrid.send(email, function(err, json) { });
+``` 
 
 #### setTos
 
+**Note**: The `setTos()` method now utilizes the Web API as opposed to using the X-SMTPAPI header. Please refer to the note posted on the top of this page. In order to use the header, you will need to use the `setSmtpapiTos()` method.
+
 ```javascript
 var email     = new sendgrid.Email(); 
 email.setTos(['[email protected]', '[email protected]']);
 sendgrid.send(email, function(err, json) { });
 ```
 
+#### setSmtpapiTos
+
+```javascript
+var email = new sendgrid.Email();
+email.setSmtpapiTos(["[email protected]","[email protected]"]);
+sendgrid.send(email, function(err, json) { });
+```
+
 #### setFrom
 
 ```javascript

lib/email.js

@@ -59,12 +59,22 @@ Email.prototype.setHeaders = function(object_literal) {
 };
 
 Email.prototype.addTo = function(to) {
+  this.to.push(to);
+  return this;
+};
+
+Email.prototype.setSmtpapiTos = function(tos) {
+  this.smtpapi.setTos(tos);    
+  return this;
+};
+
+Email.prototype.addSmtpapiTo = function(to) {
   this.smtpapi.addTo(to);
   return this;
 };
 
 Email.prototype.setTos = function(tos) {
-  this.smtpapi.setTos(tos);
+  this.to = tos;
   return this;
 };
 

package.json

@@ -10,7 +10,7 @@
   ],
   "name": "sendgrid",
   "description": "Official SendGrid NodeJS library.",
-  "version": "1.9.2",
+  "version": "2.0.0",
   "homepage": "http://sendgrid.com",
   "repository": {
     "type": "git",

test/lib/email.test.js

@@ -45,18 +45,6 @@ describe('Email', function () {
       expect(format.to).to.equal(payload.to);
     });
 
-    it('should not have multiple TOs if as an array but also set on smtpapi via addTo', function() {
-      var payload     = Object.create(default_payload);
-      payload.to      = ['[email protected]', '[email protected]'];
-      var email       = new Email(payload);
-      email.addTo(payload.to[0]);
-      email.addTo(payload.to[1]);
-
-      var format      = email.toWebFormat();
-
-      expect(format.to).to.equal(payload.from);
-    });
-
     it('should have multiple BCCs if as an array', function() {
       var payload     = Object.create(default_payload);
       payload.bcc     = ['[email protected]', '[email protected]'];
@@ -119,11 +107,50 @@ describe('Email', function () {
       var payload     = Object.create(default_payload);
       payload.to      = "";
       var email       = new Email(payload);
-      email.addTo("[email protected]");
+      email.addSmtpapiTo("[email protected]");
       var format = email.toWebFormat();
 
+      expect(format.to).to.not.be.empty;
       expect(JSON.parse(format['x-smtpapi']).to).to.not.be.empty;
+    });
+
+    it('should have to addresses if there is no tos set but there are smtpapi tos set', function() {
+      var payload     = Object.create(default_payload);
+      payload.to      = "";
+      var email       = new Email(payload);
+      email.setSmtpapiTos(["[email protected]", "[email protected]"]);
+      var format = email.toWebFormat();
+
+      expect(format.to).to.not.be.empty;
+      expect(JSON.parse(format['x-smtpapi']).to).to.not.be.empty;
+      expect(JSON.parse(format['x-smtpapi']).to).to.be.an.array;
+    });
+
+    it('should have a to address using addTo if there is no smtpapi to', function(){
+      var payload = Object.create(default_payload);
+      payload.to = "";
+      var email = new Email(payload);
+      email.addTo('[email protected]');
+      email.addTo('[email protected]');
+      var format = email.toWebFormat();
+
+      expect(format.to).to.not.be.empty;
+      expect(format.to[0]).to.equal('[email protected]');
+      expect(format.to[1]).to.equal('[email protected]');
+    });
+
+    it('should have a to addresses using setTos if there is no smtpapi to', function(){
+      var payload = Object.create(default_payload);
+      payload.to = "";
+      var email = new Email(payload);
+      email.setTos(['[email protected]', '[email protected]']);
+
+      var format = email.toWebFormat();
+
       expect(format.to).to.not.be.empty;
+      expect(format.to).to.be.an.array;
+      expect(format.to[0]).to.equal('[email protected]');
+      expect(format.to[1]).to.equal('[email protected]');
     });
 
     it("should set a fromname if one is provided", function() {

test/lib/sendgrid.test.js

@@ -12,7 +12,7 @@ var nock  = require('nock');
 describe('SendGrid', function () {
   it('version should be set', function() {
     var sendgrid = SendGrid(API_USER, API_KEY);
-    expect(sendgrid.version).to.equal("1.9.2");
+    expect(sendgrid.version).to.equal("2.0.0");
   });
 
   it('should be an instance of SendGrid', function() {