Skip to content
⌘K
InboxAsk a human

Step 3: Aligning Plain to your CRM and/or backend

Updated by Dustin

Now that you have an understanding of our data model, you’ll want to bring your customers, accounts, and the context that enriches them, into Plain. You can do this by syncing your accounts and account fields from your CRM or your backend — having this data available in Plain allows you to create sophisticated routing, SLA policies, and workflows to optimize how your team supports your customers.

What good looks like

What we define as "good" for this step is opening any thread in Plain and seeing the proper structure and context in the sidebar:

  • The thread is attached to the customer (the individual person who reached out) and associated with the right account (the company, workspace, or organization they belong to)

  • The account carries the account fields your team cares about when triaging (at minimum, the customer's plan)

  • The account's tier is populated automatically from that plan field

Essentially, you want a clear mental picture of what belongs on the person vs. the organization vs. the conversation, and you want your account data flowing in from one source of truth (your CRM or your backend) so your routing has something real to key on.

What to consider

First, decide whether Plain's default account grouping matches how your product works. Out of the box, Plain groups customers into accounts automatically by email domain — everyone @acme.com lands in the Acme account with zero setup. For most small B2B teams, this is often the only grouping mechanism you need. You only need to create explicit accounts (via a CRM integration or the API) when email domains don't reflect how you support people. For example:

  • One company has multiple workspaces or teams in your product on different plans, and support needs to know which workspace a thread is about

  • Customers sign up with personal addresses (gmail.com, outlook.com)

  • Agencies, contractors, or partners work across several of your customer organizations

Second, consider the timing of when accounts get created relative to when threads arrive. In Plain, a thread's account is inferred once, at the moment the thread is created. If you turn on your inbound channels before your accounts and customer memberships exist, those threads are created without that account attached — adding a customer to an account later does not retroactively update threads that have already been created.

Third, consider your source of truth for customer plan data. Getting your CRM sync or API data sync in place before you cut live traffic over (or knowing how to backfill open threads via the sidebar or via the API using the updateThreadAccount mutation) will save you the headache of figuring out why existing threads don’t have an account associated with them.

How to implement

Step 1: Bring account fields into Plain

You don't need to over-engineer this on day one — pick the 2-3 account fields that actually change how you handle a thread (usually plan, MRR / ARR, and account_owner).

  • If you're using a CRM:

    • Head to Settings → Integrations, and connect HubSpot, Salesforce, or Attio

      Connect HubSpot from Settings → Integrations, then approve access.
    • Then, select the list of active customer companies you want in Plain, and choose which company properties to sync across as account fields.

      Pick a HubSpot segment, show the company fields you want to sync, and turn sync on.
  • If you're pushing from your backend: Create your field schema using upsertAccountFieldSchema, then have your backend upsert the account, customer, and field values. If you don't want to write the boilerplate yourself, hand an LLM our accounts guide, our GraphQL schema, and a machine user API key, and ask it to generate an idempotent sync script. The abbreviated shape:

mutation { upsertAccount(input: { identifier: { externalId: "acct_8f2a" } name: "Acme (production)" externalId: "acct_8f2a" url: { value: "https://admin.yourproduct.com/accounts/acct_8f2a" } }) { account { id } } } mutation { upsertAccountField(input: { accountFieldIdentifier: { accountIdentifier: { externalId: "acct_8f2a" } externalFieldId: "plan" } type: STRING_TYPE stringValue: "Enterprise" }) { accountField { id } } }

And to link a customer to that account from your backend, call upsertCustomer and addCustomerToAccounts.

  • If you’re creating them manually (not recommended): Head to Settings > Account fields and click + New account field in the top right corner of the page. Then select the field type, name it, and add option values (if applicable).

Create a Plan dropdown account field in Settings → Account fields.

Step 2: Assign accounts (and threads) to tiers

A tier (Enterprise, Pro, Free) is how Plain segments your customers for routing, queue filtering, default thread priority, and SLA policies.

Normally, tiers live on the account, and a new thread picks up its account's tier when it's created. If the account's tier changes later, Plain re-tiers that account's Todo and Snoozed threads; Done threads keep the tier they had. You can also set a default tier in Settings → Tiers (isDefault), which catches any thread whose account doesn't belong to a specific tier yet.

The rest of this series uses a tier named Enterprise. The Tier row in Field mappings creates a tier for each value of your plan field, so if that field includes Enterprise, you're set once mapping is on and your test account has that value. If it doesn't, create a tier named Enterprise under Settings → Tiers.

There are four ways to set a tier in Plain — three at the account level and one at the thread level:

  1. Automatically via tier mapping (recommended if you have a plan account field):

    If you have a text account field with a fixed list of values (like plan from your CRM or backend), Plain's tier mapping creates a tier for each option in that field and keeps every account's tier in sync automatically as their field value changes. (Free-text, number, boolean, and multi-select fields aren't eligible, because Plain needs a fixed list of options to create tiers from.)

    • Head to Settings → Account fields

    • Locate the Tier row under Field mappings, select your field from the dropdown, and click Save

In the Field mappings card, map Tier to your Plan field, then save.
  1. Manually on the account in the UI:

    If you only have a handful of high-touch or VIP accounts, you don't need automation at all. Create your tiers under Settings → Tiers, open the account's page in Plain, click the Tier attribute in the sidebar, then pick the appropriate tier from the list. If a tier-mapped account field is already setting the account's tier, that row is locked to a read-only state in the UI.

    Set an account's tier by hand from its Tier row.
  2. Programmatically on the account via the API:

    If your backend already manages billing and plan changes (for example, in a Stripe webhook handler), you can create your tiers in Settings → Tiers and have your backend assign accounts to them directly using updateAccountTier (for a single account) or addMembersToTier / removeMembersFromTier (in bulk).

  3. Per-thread in the thread's details, via a workflow, or via the API (Set tier / updateThreadTier):

    Even when an account has a tier (or no tier at all), you can set or override the tier on an individual thread. In the thread's details card, locate the Thread tier row and click the dropdown button to pick a tier for that thread; in a workflow, use the Set tier workflow action; from your backend, call updateThreadTier. Each of these changes only affect that specific thread's tier, not the account's. That's useful when a specific conversation needs higher-tier treatment based on something on the thread itself (like a VIP label, a specific support email address, or an Account field condition).

    Change a single thread's tier from its Thread tier row.

Some gotchas to be aware of:

  • Account membership changes don't backfill onto existing threads. Adding a customer to an account (via CRM sync, addCustomerToAccounts, or linking a Slack channel) only affects new threads created from that point forward. Any threads that were already created before the customer belonged to that account stay as they were — update them from the thread sidebar, or ask your LLM to write a short script that calls updateThreadAccount across those threads.

  • Creating an account via upsertAccount and creating a customer via upsertCustomer are separate calls — creating an account doesn't automatically add customers to it unless they match its domain or you call addCustomerToAccounts.

  • Accounts created manually in the UI need an externalId too: the Create account dialog asks for an External ID alongside the name, and the API requires one as well. If you plan to sync from your backend, use the identifier your backend already uses (for example, your internal account ID) so upsertAccount matches the existing account instead of creating a duplicate.

  • Domain-based accounts continue to be created automatically alongside API or CRM accounts. If you only want explicit accounts in your workspace, you can toggle off Show domain-based accounts in Settings → Accounts.

Turn off Show domain-based accounts in Settings → Accounts.

How to verify if this step is working/complete

  1. Open a test thread from Step 1 (or any customer record in Plain) and look at the right-hand sidebar. Confirm Tier on that account is Enterprise before you move on.

  2. Confirm the Customer is linked to the expected Account (either matched automatically by their email domain, or linked from your CRM/API).

  3. Click into the Account page and confirm your Account fields (like plan) are visible and that Tier is Enterprise, from tier mapping or because you set it on the account.

Troubleshooting/FAQ

A thread came in, but there's no account on it (or adding a customer to an account didn't update their open threads)

Plain only infers and sets a thread's account at the exact moment the thread is created. Changes to a customer's account membership later on (whether from a CRM sync finishing, calling addCustomerToAccounts, or linking a Slack channel) only apply to future threads — they never retroactively update threads that have already been created. Here is where that timing gap shows up and how to stay ahead of it:

Setup & migration order (threads arrived or were imported before accounts were synced)

  • The threads you should have at this point are the tests you sent in Step 1. Historical import is Step 4, and it should run after this sync so those threads are created with an account already in place. If a Step 1 test thread has no account, or you already imported history before this sync, those threads were created before the customer belonged to the account.

  • Try this: Finish this sync before the Step 4 import and before you redirect live mail. For threads that already exist, set the account from the thread sidebar or with updateThreadAccount.

Signup / onboarding race condition (customer writes in before the hourly CRM sync runs)

  • Plain's CRM integrations poll roughly once an hour. If a brand-new user signs up in your app and opens a support thread five minutes later, the CRM sync hasn't created their account or linked them to it yet, so the thread is created with no explicit account.

  • Try this: Trigger upsertAccount, upsertCustomer, and addCustomerToAccounts synchronously from your product's signup or workspace-creation flow rather than relying on the hourly CRM poll for new signups.

Slack channel connected in Step 1 before it was linked to an account

  • If you invite the Plain bot to #ext-acme and a customer posts before you've linked #ext-acme to the Acme account (or if the poster is a contractor without an @acme.com email), the thread is created before the channel association exists.

  • Try this: Make linking the Slack channel on the Account page (with Auto-link set to Anyone who posts) part of your customer channel provisioning checklist before inviting customers into the channel.

Customer belongs to multiple accounts, and none of them have a tier:

  • When a customer is a member of two or more explicit accounts (say, Acme Staging and Acme Prod) and neither account has a higher-priority tier to break the tie at thread creation, Plain leaves the thread's account blank rather than guessing wrong.

  • Try this: Pass accountIdentifier explicitly when creating threads from your in-app form, or assign tiers to your production accounts so the highest-priority tier wins the tie automatically.

How to update threads that have already been created

Because Plain won't backfill the account automatically after creation, you have two ways to update existing threads:

  1. In the UI: Open the thread, find the Account row in the right-hand sidebar, click No account (or the Account actions menu if an account is already set), and search for the account you want to set on the thread.

  2. Via script + API (for a batch of threads): Hand an LLM our GraphQL schema and ask it for a script that fetches the affected threads (e.g. open threads for that customer or with no account) and calls updateThreadAccount on each one:

mutation { updateThreadAccount(input: { threadId: "th_01J..." accountIdentifier: { externalId: "acct_8f2a" } }) { thread { id } } }

(If you want your Step 6 workflows to react when you attach an account to an existing thread, make sure those workflows also trigger on Thread account updated / Thread tier updated, not only Thread created.)

One company is split across two or more accounts

Colleagues at that company are likely writing in from multiple email domains (e.g. acme.com, acme.io, or a regional domain) and Plain created a separate domain-based account for each.

Try this: When onboarding an enterprise or multi-domain customer, add their secondary domains under Alternate domains on their primary Account page upfront, and link their shared Slack channel to that same account with Auto-link set to Anyone who posts.

Add an alternate domain to an account and press Enter.
The Tier field mapping isn't assigning accounts to tiers (or my plan field isn't in the dropdown).

The Tier row in Field mappings only accepts text account fields with a fixed list of values, and accounts with an empty value for that field receive no tier.

Try this: Define your plan field as a text field with a fixed list of values in your CRM or via upsertAccountFieldSchema before syncing data, and configure one tier in Settings → Tiers as your workspace Default tier so accounts with a missing plan value still fall into a known baseline tier.