feat: sanity-check email address and address lists when adding to a message (#981)

Fixes #980

When sending an email and providing an empty list of BCCs the request fails with BadRequest as outlined here: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.bcc

We want to inform the consumer that this is the case otherwise it may lead to email sending silently failing.

Author: indy-singh

src/SendGrid/Helpers/Mail/SendGridMessage.cs

@@ -262,6 +262,7 @@ public void AddTos(List<EmailAddress> emails, int personalizationIndex = 0, Pers
         /// </summary>
         /// <param name="email">Specify the recipient's email.</param>
         /// <param name="name">Specify the recipient's name.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when the email parameter is null or whitespace</exception>
         public void AddCc(string email, string name = null)
         {
             if (string.IsNullOrWhiteSpace(email))
@@ -278,8 +279,14 @@ public void AddCc(string email, string name = null)
         /// <param name="email">An email recipient that may contain the recipient’s name, but must always contain the recipient’s email.</param>
         /// <param name="personalizationIndex">Specify the index of the Personalization object where you want to add the cc email.</param>
         /// <param name="personalization">A personalization object to append to the message.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when the email parameter is null</exception>
         public void AddCc(EmailAddress email, int personalizationIndex = 0, Personalization personalization = null)
         {
+            if (email == null)
+            {
+                throw new ArgumentNullException("email");
+            }
+
             if (personalization != null)
             {
                 personalization.Ccs = personalization.Ccs ?? new List<EmailAddress>();
@@ -333,8 +340,20 @@ public void AddCc(EmailAddress email, int personalizationIndex = 0, Personalizat
         /// <param name="emails">A list of cc recipients. Each email object within this array may contain the recipient’s name, but must always contain the recipient’s email.</param>
         /// <param name="personalizationIndex">Specify the index of the Personalization object where you want to add the cc emails.</param>
         /// <param name="personalization">A personalization object to append to the message.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when the emails parameter is null</exception>
+        /// <exception cref="System.InvalidOperationException">Thrown when the emails parameter is empty</exception>
         public void AddCcs(List<EmailAddress> emails, int personalizationIndex = 0, Personalization personalization = null)
         {
+            if (emails == null)
+            {
+                throw new ArgumentNullException("emails");
+            }
+
+            if (emails.Count == 0)
+            {
+                throw new InvalidOperationException("Sequence contains no elements");
+            }
+
             if (personalization != null)
             {
                 personalization.Ccs.AddRange(emails);
@@ -383,6 +402,7 @@ public void AddCcs(List<EmailAddress> emails, int personalizationIndex = 0, Pers
         /// </summary>
         /// <param name="email">Specify the recipient's email.</param>
         /// <param name="name">Specify the recipient's name.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when the email parameter is null or whitespace</exception>
         public void AddBcc(string email, string name = null)
         {
             if (string.IsNullOrWhiteSpace(email))
@@ -399,8 +419,14 @@ public void AddBcc(string email, string name = null)
         /// <param name="email">An email recipient that may contain the recipient’s name, but must always contain the recipient’s email.</param>
         /// <param name="personalizationIndex">Specify the index of the Personalization object where you want to add the bcc email.</param>
         /// <param name="personalization">A personalization object to append to the message.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when the email parameter is null</exception>
         public void AddBcc(EmailAddress email, int personalizationIndex = 0, Personalization personalization = null)
         {
+            if (email == null)
+            {
+                throw new ArgumentNullException("email");
+            }
+
             if (personalization != null)
             {
                 personalization.Bccs = personalization.Bccs ?? new List<EmailAddress>();
@@ -454,8 +480,20 @@ public void AddBcc(EmailAddress email, int personalizationIndex = 0, Personaliza
         /// <param name="emails">A list of bcc recipients. Each email object within this array may contain the recipient’s name, but must always contain the recipient’s email.</param>
         /// <param name="personalizationIndex">Specify the index of the Personalization object where you want to add the bcc emails.</param>
         /// <param name="personalization">A personalization object to append to the message.</param>
+        /// <exception cref="System.ArgumentNullException">Thrown when the emails parameter is null</exception>
+        /// <exception cref="System.InvalidOperationException">Thrown when the emails parameter is empty</exception>
         public void AddBccs(List<EmailAddress> emails, int personalizationIndex = 0, Personalization personalization = null)
         {
+            if (emails == null)
+            {
+                throw new ArgumentNullException("emails");
+            }
+
+            if (emails.Count == 0)
+            {
+                throw new InvalidOperationException("Sequence contains no elements");
+            }
+
             if (personalization != null)
             {
                 personalization.Bccs.AddRange(emails);

tests/SendGrid.Tests/PreSendEmailValidation/WhenCreatingASendGridMessage.cs

@@ -0,0 +1,52 @@
+using System;
+using System.Collections.Generic;
+using SendGrid.Helpers.Mail;
+using Xunit;
+
+namespace SendGrid.Tests.PreSendEmailValidation
+{
+    public class WhenCreatingASendGridMessage
+    {
+        [Fact]
+        public void WithAnEmptyListOfBlindCarbonCopiesThenAnExceptionIsThrown()
+        {
+            var sendGridMessage = MailHelper.CreateSingleEmail(new EmailAddress(), new EmailAddress(), string.Empty, string.Empty, string.Empty);
+            Assert.Throws<InvalidOperationException>(() => { sendGridMessage.AddBccs(new List<EmailAddress>()); });
+        }
+
+        [Fact]
+        public void WithANullListOfBlindCarbonCopiesThenAnExceptionIsThrown()
+        {
+            var sendGridMessage = MailHelper.CreateSingleEmail(new EmailAddress(), new EmailAddress(), string.Empty, string.Empty, string.Empty);
+            Assert.Throws<ArgumentNullException>(() => { sendGridMessage.AddBccs(null); });
+        }
+
+        [Fact]
+        public void WithANullBlindCarbonCopyThenAnExceptionIsThrown()
+        {
+            var sendGridMessage = MailHelper.CreateSingleEmail(new EmailAddress(), new EmailAddress(), string.Empty, string.Empty, string.Empty);
+            Assert.Throws<ArgumentNullException>(() => { sendGridMessage.AddBcc(null, 0); });
+        }
+
+        [Fact]
+        public void WithAnEmptyListOfCarbonCopiesThenAnExceptionIsThrown()
+        {
+            var sendGridMessage = MailHelper.CreateSingleEmail(new EmailAddress(), new EmailAddress(), string.Empty, string.Empty, string.Empty);
+            Assert.Throws<InvalidOperationException>(() => { sendGridMessage.AddCcs(new List<EmailAddress>()); });
+        }
+
+        [Fact]
+        public void WithANullListOfCarbonCopiesThenAnExceptionIsThrown()
+        {
+            var sendGridMessage = MailHelper.CreateSingleEmail(new EmailAddress(), new EmailAddress(), string.Empty, string.Empty, string.Empty);
+            Assert.Throws<InvalidOperationException>(() => { sendGridMessage.AddCcs(new List<EmailAddress>()); });
+        }
+
+        [Fact]
+        public void WithANullCarbonCopyThenAnExceptionIsThrown()
+        {
+            var sendGridMessage = MailHelper.CreateSingleEmail(new EmailAddress(), new EmailAddress(), string.Empty, string.Empty, string.Empty);
+            Assert.Throws<ArgumentNullException>(() => { sendGridMessage.AddCc(null, 0); });
+        }
+    }
+}