Get All Contacts from List

[NEMA-IT]

Is it possible to get all the contacts for a specific list, without using the legacy API or fetching all the contacts? I plan to have over 100K contacts and want to use the API to synchronize list memberships with my CRM.

[NEMA-IT]

To answer my own question, SendGrid support explained to me that this is not possible. The legacy API gives you the ability to fetch all contacts from a list. For new customers who don't have access to the legacy API, they have to export the contacts into CSV.

[Jericho]

Exporting to a CSV file is probably the best solution since you have such a large number of contacts but unfortunately you can't automate the entire process: you can request for your contacts to be exported, and then you have to wait to receive an email telling you that your export is ready. This email will contain a very important code (called 'UUID') and use you will be able to use this code to subsequently download the CSV file. StrongGrid can help you with requesting the export and with downloading the CSV file but you still need to manually find the UUID from the email. To my knowledge there is no way to automate this part of the process.

By the way, I provided feedback (see bullet point number 8) about this convoluted process which, as per usual, was promptly ignored by SendGrid. 😒 😞

Having said all this, let me offer a possible workaround: StrongGrid offers a way to Search for contacts that match criteria that you define
(like "firstname = 'Bob'", for example). You can even join multiple criteria with logic operators AND or OR. Seems to me that you could probably create a query to search for contacts that are associated with a given listsId. I have never used SendGrid's search end point with such a large number of contacts though, so this might not be a good solution for you in the end but it's worth investigating.

Here's a code snippet that demonstrates how to search for contacts with two criteria:

var firstNameCriteria = new SearchCriteriaEqual<ContactsFilterField>(ContactsFilterField.FirstName, "John");
var LastNameCriteria = new SearchCriteriaEqual<ContactsFilterField>(ContactsFilterField.LastName, "Doe");
var searchResult = await client.Contacts.SearchAsync(new[] { firstNameCriteria, LastNameCriteria }, cancellationToken).ConfigureAwait(false);

This is a simple query just to give you an idea how it works. Notice the absence of logical operator between the criteria. By default StrongGrid assumes the 'ANDlogical operator but you could modify this query to join them withOR`.

Off the top of my head, I came up with this sample which should get you started with your search:

var listCriteria = new SearchCriteriaEqual<ContactsFilterField>(ContactsFilterField.ListIds, "<your list id>");
var searchResult = await client.Contacts.SearchAsync(listCriteria, cancellationToken).ConfigureAwait(false);

As I said before, this may not work for you due to the large number of contacts but I thought I would present this possible alternative and let you investigate whether it works for you.

Let me know if this alternative works for you.

[Jericho]

Please disregard my comment about an email containing a UUID being sent to you: it applies only to scenarios when exporting email activities to a CSV file. I guess I got these two scenarios mixed up.

[NEMA-IT]

You're right to be warry of using search for a large number of contacts. SendGrid says the request will timeout if longer than 20 seconds. I queried a list of 1K contacts and it took ~4 seconds.

I think I found the solution by using the following query:

"CONTAINS(list_ids, 'List ID') AND email LIKE 'a%'"

The above will return all contacts with email starting with "A". The idea is paginate the query by looping through the alphabet. I've confirmed this query works with Postman, but can't express it using StrongGrid.

How can I use the "CONTAINS" function to query list_ids? Or is there a way to pass a string query to the Contacts.SearchAsync() function?

(The "IN" or "=" operators will not work with the list_ids field)

[Jericho]

Unfortunately StrongGrid does not provide support for what SendGrid calls "well-defined functions" for segmenting (such as "Contains" for example). This feature is tracked in #317. To be honest, I neglected to implement this functionality because I didn't think there was much interest in it.

Another detail I had forgotten about: the documentation states that Only the first 50 contacts that meet the search criteria will be returned. So, even if we add support for 'Contains', I doubt it would resolve the issue for you.

[Jericho]

I will add "CONTAINS" in the next release. See #448 .

[Jericho]

I have reviewed the 'Export Contacts' documentation and it seems that SendGrid may have implemented some changes since the last time I looked at it. Seems like the "we'll send you an email with a link that you must click on to download the CSV file(s)" step is now optional. It was a required step back in 2018. This means we can automate the export process from start to finish.

Here's what I have in mind:

var exportJobId = await client.Contacts.ExportAsync(FileType.Csv, null, null, default, cancellationToken).ConfigureAwait(false);

var elapsed = Stopwatch.StartNew();
var jobCompleted = false;
while (true)
{
	var job = await client.Contacts.GetExportJobAsync(exportJobId, cancellationToken).ConfigureAwait(false);
	if (job.Status == JobStatus.Ready)
	{
		jobCompleted = true;
		break;
	}
	else
	{
		await Task.Delay(500, cancellationToken).ConfigureAwait(false);
	}

	// Make sure we don't loop indefinetly.
	// I arbitrarilly decided to wait no more than 5 seconds, because it seems like a reasonable amount of time.
	// In your case, due to the large number of contacts, I imagine it will take much longer than 5 seconds.
	if (elapsed.Elapsed >= TimeSpan.FromSeconds(5))
	{
		elapsed.Stop();
		break;
	}
}

if (jobCompleted)
{
	var tempPath = System.IO.Path.GetTempPath();
	await client.Contacts.DownloadExportFilesAsync(exportJobId, tempPath, cancellationToken).ConfigureAwait(false);
}

Note 1: SendGrid can decide the break up an export job into several CSV files to keep each one to a manageable size
Note 2: each CSV file may be compressed. Currently, it is your responsibility to decompress the content of each file after you download them but I am working on an improvement that will allow you to indicate that StrongGrid should automatically decompress the files

[Jericho]

FYI: new version (0.90.0) has been released with support for the CONTAINS search criteria and also the ability to automatically decompress GZIP'ed files when exporting contacts.

Let me know if this helps.