Getting Started with the Marketing Campaigns V2 Segmentation API

The Segmentation V2 API is in public beta. V2 segments can now be created and edited through both the UI and API.

You can see both V1 and V2 segments you have created with their contacts in the UI. While the UI only supports creation of V2 segments, you can still edit or delete either V1 or V2 segments in the UI. Both V1 and V2 segments can be exported and used as an audience for a Single Send or Automation. See the V2 Segmentation API documentation for more information.

The V2 Segmentation API allows you to create and manage segments using a subset of SQL that includes statements and operations necessary to define any segment. In addition, this version of the Segmentation API exposes the contact_data and event_data tables to enable SQL-compatible queries.

You can use this API to engage your contacts that meet specific criteria that you specify from a set of data. The segment can be based anything from a combination of criteria on a set of the contacts’ attributes, as well as any contacts that have specific engagement events that also satisfy the aforementioned criteria.

Benefits of This New API

The Segmentation V2 API uses SQL instead of the proprietary SendGrid Query Language (sgql) to specify segments, meaning you do not need to learn a new query language and can leverage skills in widely used SQL. Since this version of the API exposes the contact_data and event_data tables and gives you SQL access, any specification that is expressible via SQL that would result in a meaningful segment given the structure of the table is possible. Some segments that we can build now that we couldn’t with V1 are:

  • Segments built over multiple engagement events.
  • Segments of contacts that have never been engaged.

Limitations of This New API

  • Not all of SQL is supported, meaning the Segmentation V2 API's query language is a SQL-compatible subset of SQL.
  • You must select contact_id, and updated_at in the primary select clause. This in turn constrains the rest of the query in specific ways which is an effect of how SQL works. The examples in the reference will clarify these aspects of the V2 API.
  • None of the data modification constructs of SQL are supported.


Before you can use the V2 Segmentation API you will need to do the following:

  1. Create or log into your SendGrid account.
  2. Navigate to Settings and create an API Key.
  3. Upload contacts using the UI or API.

Create a Segment

Below are some examples of segments you can create using the V2 Segmentation API. For more code samples and use cases, see the Marketing Campaigns Segmentation V2 Query Reference.

Example Body

"name":"string (required)",
"query_dsl":"SQL string (required)",
"parent_list_ids":"array[string] (optional)"

Select all contacts

SELECT contact_id, updated_at FROM contact_data 

Select all contacts who engaged with an email by clicking

SELECT c.contact_id, c.updated_at 
FROM contact_data as c 
JOIN event_data as e ON c.contact_id= e.contact_id WHERE e.event_type = ‘clicked’

Upgrade a V1 Segment to V2

Any existing V1 Segments can be upgraded to a V2 Segment via the UI or via the API directly.



  1. In the UI, click on the V1 Segment that you want to upgrade to V2.
  2. Under Segment Options, select duplicate.
  3. Once you have saved your new V2 Segment, it is safe to delete the original V1 Segment.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more