External segments

External segments let you target people already stored in your own database, like your CRM or data warehouse, instead of exporting them to a CSV and re-uploading it every time the list changes. You give Pushwoosh a SQL query that returns the right user IDs, and Pushwoosh keeps rerunning that query to keep the segment up to date. Once it’s set up, you can use these users the same way as any other segment.

Developer assistance needed

You’ll need help from your developer or database administrator to set up the connection. Share this guide with them to get started.

Setting up a connection touches your production database. Before you start, have your developer or database administrator:

• Prepare a read-only user (or, for BigQuery, a read-only service account)
• Confirm the query you plan to use
• If the database is behind a firewall, ask Pushwoosh support which IP addresses to allow

Create an external segment

Name the segment and choose the database

1. Go to Audience → External Segments.
2. Click Create external segment.

3. Enter a Name for the segment (up to 100 characters).
4. Choose the Database type: PostgreSQL, MySQL, Google BigQuery, or Microsoft SQL Server / Fabric.

Fill in the connection fields

PostgreSQL and MySQL

For PostgreSQL and MySQL, fill in:

• Host and Port: the address of your database server. Pushwoosh requires a publicly reachable host and rejects private, internal, or loopback addresses when you check the connection or save the segment.
• Database: the database name.
• User and Password: credentials for a read-only account.
• SSL mode (PostgreSQL only, since MySQL connections don’t use TLS) sets how SSL/TLS, the protocol that encrypts the connection, applies to your database connection. Ask your database administrator which mode to use:
  • Disable: no encryption.
  • Require: encrypts the connection, but doesn’t check the database server’s identity.
  • Verify CA: encrypts the connection and checks that the server’s certificate was issued by a trusted certificate authority (CA).
  • Verify full: same as Verify CA, and also checks the certificate matches your database’s hostname. The strongest option.
• For any mode other than Disable, provide the CA certificate under Certificate source (Upload files or Paste PEM), plus a Client certificate and Client key if your database requires them.

BigQuery

For Google BigQuery, fill in:

• Project ID: the GCP project that holds your dataset.
• Service account JSON: the key for a service account with BigQuery read access.
• Location: the dataset’s region (for example, EU, US, or europe-west3). Leave it empty to resolve the location automatically from the dataset.

SQL Server / Fabric

For Microsoft SQL Server / Fabric, fill in:

• Host and Port: the address of your database server, or your Fabric SQL analytics endpoint. Pushwoosh requires a publicly reachable host and rejects private, internal, or loopback addresses when you check the connection or save the segment.
• Database: the database name.
• User and Password: credentials for a read-only account.
• Microsoft Entra tenant ID: optional. Leave it empty for a SQL Server login. For Microsoft Fabric, whose SQL analytics endpoint has no SQL logins, set it to sign in as a service principal instead. Enter its application (client) ID as User and its client secret as Password.

Enter the query

1. Enter the Query. It must return a single column named user_id, with one row per user you want in the segment. For example:

SELECT user_id FROM loyalty_members WHERE tier = 'gold'

Note

The user_id values must match the Pushwoosh User IDs you’ve set for your users (the same identifier used by Build segments by User ID). A query returning IDs Pushwoosh doesn’t recognize won’t match any devices.

2. Click Check connection to confirm Pushwoosh can reach the database (times out after 30 seconds).
3. Click Check query to confirm the query runs and returns the right column (also times out after 30 seconds).

Verify and create

When both checks succeed, click Create. Pushwoosh saves the segment and adds it to the External Segments list right away.

How the segment stays up to date

Pushwoosh doesn’t run your query on a fixed schedule. Instead, it refreshes the segment based on how recently it was last used:

• If the segment’s data is less than an hour old, Pushwoosh uses the current data as-is.
• If it’s older than an hour, Pushwoosh keeps using the current data while it refreshes in the background.
• If it’s older than three hours, Pushwoosh waits for a fresh refresh before it uses the segment.

In practice, this means a segment you use regularly (for example, in a recurring journey) stays current, while a segment you rarely touch may take a moment to refresh the first time you use it again.

If a refresh fails (for example, the database becomes unreachable or the query starts erroring), Pushwoosh records the error, but the segment’s status on the External Segments list doesn’t change on its own. After you’ve fixed the issue on your end, open the segment and click Check connection to confirm the fix. The error clears automatically the next time the segment’s data refreshes successfully.

Use an external segment

Once you’ve created it, the external segment automatically appears on Audience → Segments under the same name, ready to use like any other segment, for example as a campaign or journey audience.

To combine it with other conditions, add it as a filter:

1. Go to Audience → Segments → Create Segment.
2. Click Add filter by → Segment.
3. Select your external segment by name.

The same Segment filter is available in compound filters and when you choose the audience in Audience-based entry. For more on combining segments, see Build segments by existing segments.

Check how many people are in the segment

The External Segments list doesn’t show a member count. Open the segment’s wrapper on Audience → Segments (see Use an external segment) and calculate its size there.

Manage external segments

On the External Segments list, each row shows the segment’s name, Code (the identifier used to reference the segment in API calls), database type, host, and status (valid or invalid).

• Click Edit to change the connection or query. The database type can’t be changed after creation. Create a new segment instead.
• Click Delete to remove a segment. Pushwoosh blocks the deletion while the segment is used by a campaign, journey, filter, or popup form. Remove those references first, then delete the segment. This cannot be undone.