How to get SendGrid bulk-email statuses in C#

Question

I need to send an emails (bulk sending), and I have two cases:

1. The same email sent into multiple recipients
2. Different emails sent into different recipients

How, in both cases, I can control statuses?

First case will return single x-message-id, but how it can be translated into separate status for each recipients? (delivered, opened and so on?)

Second case, I believe, need to be done by sending one-by one, is that correct? Or there is also method to send bulk emails in that case?

I'm using C# and official .NET library.

Answer 1

1. To send the same email sent to multiple recipients:

   • You can use the MailHelper.CreateSingleEmailToMultipleRecipients and you'll need to specify the text and HTML content in code. (Sample)
   • You can also use the MailHelper.CreateSingleTemplateEmailToMultipleRecipients method which will use a SendGrid Dynamic Email Template. In that case the email template is already stored in SendGrid and you simply provide the ID of the template.
   • There's a showAllRecipients named parameter which defaults to false. When false recipients cannot see other recipients, when true recipients can see other recipients.
   • I'll talk about retrieving the status's of the individual emails later.

2. To send different email to different people:

   • You can use MailHelper.CreateMultipleEmailsToMultipleRecipients which will use a single text and HTML body template, but you can add substitution tags and pass in substitution data so the email will be personalized for every recipient. (Sample)
   • You can construct a single MailMessage but use multiple Personalization objects to override any of the MailMessage properties for specific recipients. (Sample)
   • You can also construct multiple MailMessage objects and submit them individually to the API, although the above options are made for this scenario.

To send any of these emails, your API key must have the mail.send permission.

There are additional ways to send bulk email with SendGrid, which I documented here in much more detail.

---

As you noted, when you send email in bulk, only a single message ID is returned via the x-message-id header. When you later try to retrieve the details using that message ID, you will not find any messages. That is because the message ID in the x-message-id header is used as a base ID and the real message IDs will append another ID. For example, x-message-id will return "W86EgYT6SQKk0lRflfLRsA", but when you retrieve one of the individual messages, it will looks something like this: "W86EgYT6SQKk0lRflfLRsA.filterdrecv-5645d9c87f-78xgx-1-62841247-82.1".

You can retrieve these messages via the E-Mail Activity API like this:

var queryParams = JsonSerializer.Serialize(new
{
  query = $"msg_id LIKE '{messageId}%'",
  limit = 10
});

var response = await client.RequestAsync(
  method: SendGridClient.Method.GET,
  urlPath: "messages",
  queryParams: queryParams
);

Console.WriteLine(await response.Body.ReadAsStringAsync());

Take note of the query property which is has the $"msg_id LIKE '{messageId}%'" value. This query will filter to messages that begin with the message ID returned from the bulk email (messageId), and as a result retrieve all the individual messages. You cannot query these messages immediately after submitting the bulk email to SendGrid's queue as it takes some time for them to become available through the API. In my code I queried these messages every 30 seconds until the count of the recipients in the bulk email matched the messages returned.

The resulting JSON data looks like this:

{
  "messages": [
    {
      "from_email": "[email protected]",
      "msg_id": "5QSczogTRHqFtiIkLxMtWA.filterdrecv-5645d9c87f-6r2ch-1-62847C63-2D.0",
      "subject": "Sending with Twilio SendGrid is Fun",
      "to_email": "[email protected]",
      "status": "delivered",
      "opens_count": 0,
      "clicks_count": 0,
      "last_event_time": "2022-05-18T05: 01: 05Z"
    },
    {
      "from_email": "[email protected]",
      "msg_id": "5QSczogTRHqFtiIkLxMtWA.filterdrecv-5645d9c87f-6r2ch-1-62847C63-2D.1",
      "subject": "Sending with Twilio SendGrid is Fun",
      "to_email": "[email protected]",
      "status": "delivered",
      "opens_count": 0,
      "clicks_count": 0,
      "last_event_time": "2022-05-18T05: 01: 05Z"
    },
        ...
  ]
}

As you can see, this includes the status property.

Note: You must purchase additional email activity history to gain access to the Email Activity Feed API.
Note: To retrieve message via the Email Activity Feed API, your API key must have the email_activity.read permission.

This would be one way to retrieve the status of your email messages. Another way to keep track of the status of email messages would be to create a public ASP.NET endpoint configure the URL as the SendGrid Event Webhook. SendGrid will send an HTTP request to your ASP.NET endpoint for every event which you can use to update the status of email messages.

---

PS: You may already be doing this, but whether you're sending a single email to multiple recipients or multiple emails to multiple recipients, Twilio recommends setting the SendAt property on the SendGridMessage when sending bulk emails.

Quoting from the SendGrid docs:

This technique allows for a more efficient way to distribute large email requests and can improve overall mail delivery time performance. This functionality:

• Improves efficiency of processing and distributing large volumes of email.
• Reduces email pre-processing time.
• Enables you to time email arrival to increase open rates.
• Is available for free to all SendGrid customers.

I hope that answered all your questions, if not let me know. I can't wait to see what you build!