How to integrate Truelist with Salesforce

Truelist has a direct integration with Salesforce that validates the email addresses on your Contact records and writes each result back to a custom field on the Contact. This guide walks you through setup and day-to-day management.

How the integration works

When you connect Salesforce, Truelist creates a custom field called Truelist_Email_State__c (label: Truelist Email State) on your Contact object. Each sync then fetches every Contact that has an email address, runs each address through Truelist’s full validation pipeline, and writes the result back to that field.

The field is set to one of four values:

  • valid — The email address is valid and safe to send to.
  • risky — The email address may be valid but carries some risk (e.g. an address on an accept-all domain).
  • invalid — The email address is invalid and should not be sent to.
  • unknown — Truelist could not determine the validity of the email address.

Results are written back once the whole sync has been validated. If several Contacts share the same email address, they all get the same result.

You can use Truelist_Email_State__c in Salesforce list views, reports, flows, and campaign filters to act on the results.

After your first sync, Truelist validates your Contacts automatically every week, or you can switch to manual syncs and run them yourself.

Before you begin

  • A paid Truelist plan. Integrations aren’t available on the free plan: the Set up button is disabled, and automatic syncs don’t run for free accounts.
  • A Truelist team admin. Only admins on your Truelist account can save sync settings, click Sync now or delete the integration.
  • A Salesforce admin login. Connect with a user who can create custom fields on the Contact object and create and assign permission sets, typically a System Administrator. See Permissions.
  • API access. Your org’s edition must include REST API access: Enterprise, Unlimited, Performance and Developer Edition orgs do, and Professional Edition needs the API add-on.

Step-by-Step Setup

  1. Go to Settings → Integrations in your Truelist account.

  2. Find the Salesforce card under Available integrations and click Set up.

  3. Click Connect Salesforce.

    You will be redirected to Salesforce to log in and authorize Truelist. Log in as a Salesforce admin.

  4. Review the requested access and click Allow.

    Salesforce sends you back to Truelist, which then:

    • Creates the Truelist_Email_State__c custom field on your Contact object (if it doesn’t exist yet)
    • Creates a TruelistIntegration permission set (label: Truelist Integration) with read and edit access to that field
    • Assigns that permission set to the Salesforce user you connected with

  5. You land on the Salesforce integration settings page in Truelist. It shows your sync status, when the last sync ran, and how many of your Contacts have an email address.

  6. Click Sync now to start your first validation run.

    Note: A batch named Salesforce Contacts appears in your Truelist account so you can track the sync’s progress. Results are written back to Salesforce, not exported as a file.

A new connection starts on Enabled, sync automatically. Automatic syncs begin once your first sync has completed. To run syncs only when you choose, switch the Status to Enabled, but sync manually (see Sync settings).

Permissions

When you click Allow, Truelist asks Salesforce for these OAuth scopes:

  • Manage user data via APIs (api) — to read your Contacts, create the custom field and permission set, and write results back.
  • Perform requests at any time (refresh_token, offline_access) — so weekly syncs can run without you logging in again.

Truelist reads each Contact’s Id, Email, First Name and Last Name. It only writes to the Truelist_Email_State__c field.

Setup needs a Salesforce user who can create custom fields and create and assign permission sets, which is why we recommend a System Administrator. If the user you connect with can’t do this, setup stops with the error “Couldn’t create the Truelist Email State field on Contact. Please reconnect as a Salesforce admin”. Click Reconnect Salesforce and log in as an admin.

Making Truelist_Email_State__c visible on Contact records

The custom field is created and filled in automatically, but Salesforce does not add new fields to page layouts. To see the field on a Contact record:

  1. In Salesforce, go to Setup → Object Manager → Contact → Page Layouts.
  2. Open the page layout you use (e.g. Contact Layout).
  3. Drag Truelist Email State from the field list into the layout section where you want it to appear.
  4. Click Save.

The field will now appear on all Contact record pages that use that layout.

The TruelistIntegration permission set gives access to the field only to the user who connected Salesforce. To let other users see the field, assign the Truelist Integration permission set to them, or grant access to the field through their profile.

Managing the Integration

Sync settings

Use the Status dropdown, then click Save:

  • Enabled, sync automatically — Truelist validates your Contacts once a week, starting after your first sync.
  • Enabled, but sync manually — Syncs only run when you click Sync now.

Syncing now

Click Sync now to validate all your Salesforce Contacts with an email address right away.

Deleting the integration

Click Delete Salesforce integration to disconnect Truelist from your Salesforce org. This stops all syncing. It does not delete any data — the Truelist_Email_State__c field, its existing values and the TruelistIntegration permission set stay in Salesforce, but the field is no longer updated. You can reconnect at any time.

Deleting the integration in Truelist doesn’t revoke Truelist’s access token in Salesforce. To revoke it as well, search for Connected Apps OAuth Usage in Salesforce Setup and revoke Truelist’s access.

Troubleshooting

If Truelist can’t sync, it disables the integration and shows the reason on the Salesforce settings page, with a Reconnect Salesforce button in place of Sync now. For a revoked token or missing credits, you also get an email. Syncing is paused until you reconnect.

  • “Salesforce access was revoked or has expired. Please reconnect the integration” — Truelist refreshes its access token automatically, but the refresh failed. This happens when access is revoked in Salesforce, or the connected user is deactivated or loses access. Click Reconnect Salesforce.
  • “Couldn’t create the Truelist Email State field on Contact. Please reconnect as a Salesforce admin” — The user you connected with can’t create custom fields or permission sets. Click Reconnect Salesforce and log in as an admin.
  • “Your account does not have enough credits to sync” — Your account had fewer credits than the number of Contacts with an email address. Add credits, then click Reconnect Salesforce.

Reconnecting re-uses the existing Truelist_Email_State__c field and sets the Status back to Enabled, sync automatically. If you sync manually, switch it back after reconnecting.

Using validation results in Salesforce

Once a sync completes, each Contact’s Truelist_Email_State__c is updated. Here are common ways to act on the results.

Create a list view of invalid contacts

  1. Go to the Contacts tab in Salesforce.
  2. Create a new list view.
  3. Add a filter: Truelist Email State equals invalid.
  4. Save the view.

Use this list to suppress, archive, or remove contacts with bad email addresses before your next campaign.

Build a report to audit your contact quality

  1. Go to Reports → New Report → Contacts.
  2. Add Truelist Email State as a column and as a grouping field.
  3. Run the report to see a breakdown of valid, invalid, risky, and unknown contacts across your org.

Suppress invalid contacts from campaigns

When building a Salesforce Campaign or syncing to a marketing tool, filter on Truelist_Email_State__c != 'invalid' to exclude contacts with bad email addresses and protect your sender reputation.

Use results in flows or automation

You can reference Truelist_Email_State__c in any Salesforce Flow or Apex trigger. For example, add contacts marked invalid to a suppression list, or send an internal alert when a contact’s email state changes.

Frequently Asked Questions

Which Salesforce records does Truelist validate?

Contacts only, and only those with an email address. Leads, Accounts and other objects aren’t synced.

Which Salesforce editions are supported?

Any edition with REST API access: Enterprise, Unlimited, Performance and Developer Edition, plus Professional Edition with the API add-on. Truelist connects through login.salesforce.com, so sandbox orgs aren’t supported.

Do I need to be a Salesforce administrator?

You need to connect as a user who can create custom fields and create and assign permission sets, typically a System Administrator. After setup, syncs run under that connection.

Is the integration available on the free plan?

No. Integrations need a paid Truelist plan, and automatic syncs don’t run for free accounts.

How often will my contacts sync automatically?

Once a week, starting after your first sync has completed. Switch to Enabled, but sync manually if you’d rather only sync when you click Sync now.

Will Truelist re-validate contacts it has already checked?

Yes. Every sync re-validates every Contact with an email address, including ones Truelist has checked before.

Does Truelist validate all contacts or just new ones?

All of them. Each sync validates every Contact with an email address, not only the ones added since the last sync.

Will the integration modify any other contact data?

No. Truelist only writes to the Truelist_Email_State__c field. It does not modify other fields, delete Contacts, or change record ownership.

What happens if my Salesforce access token expires?

Truelist refreshes it automatically. If the refresh fails (for example, because access was revoked in Salesforce), the integration is disabled and you receive an email. Go to Settings → Integrations → Salesforce and click Reconnect Salesforce.

Why can’t I see Truelist_Email_State__c on a Contact record?

The field exists in Salesforce but needs to be added to the Contact page layout, and users other than the one who connected need access to it. See Making the field visible above.

Can I use Truelist_Email_State__c in Salesforce reports?

Yes. It’s a text field and can be used in reports, list views, flows, and filters like any other.