Step 2: Understanding Plain's data model at scale
Once your channels are connected, the next step is understanding how Plain organizes all of the data associated with those threads. Most things you’ll build (routing, workflows, SLA policies, etc.) will generally read from three core objects: customers, accounts, and threads. We’ll go through these below to help you develop a strong mental model of what these objects are and how they interact with each other.
The mental model: customers, accounts, and threads
Think of Plain's data model as three connected layers:
Customers (the individual people)
A customer is a single human being (or agent ) who contacts you, typically identified by their email address.
How customers get created:
Automatically the moment someone emails you, messages you in a connected Slack channel, or starts a chat. You can also create or update them proactively from your backend via the API with upsertCustomer or via one of our native CRM integrations.
What data lives on a customer:
Identity details — full name, short name, email address, externalId, and any customer cards that pull live per-user data from your backend.
Every customer must have an email associated with it. If a customer writes in from Slack and has their email anonymized, for example, Plain will create the customer and assign it a generated, generic email address to fulfill this requirement.
Accounts (the organizations or workspaces)
An account groups customers into the company, organization, or product workspace they belong to (if you're coming from Zendesk, think Organizations; in Intercom or HubSpot, think Companies).
A note on naming: Accounts are the standard organizational object across all new Plain workspaces. In our GraphQL schema and API permission names, you'll see the underlying entity referred to as tenant alongside the newer account queries and mutations (e.g. tenant:create / tenant:edit permissions, or {{ tenant.* }} alongside {{ account.* }} variables). They refer to the exact same object.
How customers and accounts relate (many-to-many):
One account can have many customers, and a single customer can belong to multiple accounts. That's an intentional design choice — a consultant who helps three of your customers, for example, or an engineer who belongs to both Acme (Staging) and Acme (Production), is defined as one Customer who has multiple Customer <> Account memberships.
How accounts get created (and how customers get linked to them):
Automatically by email domain: When jane@acme.com writes in, Plain matches acme.com to the Acme account (or creates it if it doesn't exist yet).
By linking a Slack channel to the account: On any account page in Plain (or via the API), you can connect one or more customer Slack channels (like
#ext-acme) directly to that account. In the account's Auto-link settings, you control how people posting in that channel get added to the account:Anyone who posts (
ALWAYS_ADD) — links everybody who messages in the channel to this account, regardless of their email domain (ideal when a customer has contractors, agency partners, or sister-company domains in their shared Slack channel).Customers without email (
IF_DOMAIN_NOT_AVAILABLE) — only links channel members who don't have a usable company email domain on their Slack profile, letting email domain matching handle everyone else.
From your CRM: Connecting HubSpot, Salesforce, or Attio syncs CRM companies into Plain as accounts and keeps their attributes updated hourly.
Via the API: Calling
upsertAccountfrom your backend with your ownexternalIdlets you create one account per workspace, org, or team in your product.
What data lives on an account:
Primary and alternate domains — these determine which customers are automatically added to this tenant)
Connected Slack channels — threads created in a connected Slack channel will be associated with that account, even if the customer writing in isn’t
External ID — for mapping back to your database)
Account fields — custom attributes you define under Settings → Account fields. These are typically synced over automatically via one of our many CRM integrations, or they can be manually set for an individual account on their account page.
Tier — the support segment (
Enterprise,Pro,Free) the account belongs to
Threads (the conversations)
Every conversation in Plain, whether it started in email, Slack, chat, the Customer Inbox, or the API, becomes a thread.
Every thread belongs to one customer, and can be associated with exactly one account (or none if Plain can't find one). When a thread is linked to an account, the thread inherits the account's context: its tier and account fields appear in the thread sidebar, allowing you to use them for automating workflows as your workspace becomes more sophisticated.
When a new thread arrives, Plain infers which account to attach to the thread using the following hierarchy:
Explicitly passed via the API: If you pass an
accountIdentifierwhen creating a thread via the API (for example, from an in-app support form that knows which workspace the user is logged into), Plain will attach that account to the thread, as long as the customer on the thread belongs to it.The Slack channel's linked account: If the message comes from a Slack channel that's linked to an account (and the channel's auto-link policy applies), Plain attaches the thread directly to that channel's account. This is true even if the person posting belongs to multiple accounts or uses a different email domain.
The account that gives the customer their highest-priority tier: If no account was specified by the API or the Slack channel, Plain looks at the accounts the customer belongs to and picks the account whose tier has the highest default thread priority. If two or more of their accounts share that top tier, Plain will not infer an account and moves on to the next step
For example, if a customer that belongs to both an
Enterpriseaccount and aFreeaccount creates a thread, that thread will be associated with the account with theEnterprisetier.
The customer's sole account membership: If a customer is only associated with a single account, then the thread inherits that account. Otherwise the thread's account is left blank.
Important timing rule: account inference only runs at thread creation. Plain runs the hierarchy above once — at the exact moment a thread is created. It doesn't re-run when a customer's account membership changes later.
That means if a customer writes in (or their historical threads are imported) before they've been added to an explicit account via your CRM sync, your API script, or a linked Slack channel, those historical threads will not automatically pick up the new account when the customer is added to it later. To update threads that were created before the customer's account membership was in place, you'll need to either:
Select the account manually from the right-hand sidebar on the thread in Plain, or
Run a quick script against the API that queries the customer's existing threads and calls
updateThreadAccountto set the account on each one. Use your LLM to write this script, use your agentic tool of choice to call the Plain MCP, or use our internal agent, Sidekick, to handle this easily without requiring extensive programming knowledge.
What data lives on a thread:
Native properties:
Status (
Todo,Snoozed,Done)Priority (
Urgent,High,Normal,Low)Labels (including team labels)
Assignees (one primary assignee plus optional co-assignees)
the applied SLA policy, and
the thread's tier (inherited from the account by default, or overridden on the thread).
The timeline: Every inbound message, outbound reply, internal note, attachment, Slack/email discussion, task, and linked issue (Linear, Jira, or incident.io).
Thread fields: Custom structured fields configured under Settings → Thread fields (text, dropdowns, booleans, numbers, currency, or dates). These are similar to account fields, except these live on the thread object instead of the account object. The easiest way to decide whether a piece of data belongs on an account field or a thread field is to ask: "Is this true about the customer's company across every conversation, or is it only true about this specific ticket?"
If it's true across every conversation (
plan,MRR,account_owner,region), put it on an account field so every future thread from that organization inherits it automatically.If it changes from ticket to ticket (
product_area,bug_severity,order_id,affected_environment,root_cause), put it on a thread field.
Troubleshooting/FAQ
A customer belongs to multiple accounts and their thread attached to the wrong one
Unless a thread comes from a linked Slack channel or passes an explicit accountIdentifier via the API, Plain picks whichever of the customer's explicit accounts has the highest-priority tier. If several share that tier, or none of them has one, Plain will only attach an account when the customer belongs to exactly one — otherwise, it leaves it blank.
Try this: If customers frequently belong to multiple workspaces in your product, pass accountIdentifier from your logged-in support form or chat authentication payload so Plain knows which workspace they're currently acting in. To fix an existing thread, switch the account manually in the thread sidebar or via updateThreadAccount.
Why do I see tenant in some API permissions or workflow variables when the UI says Account?
Account is the standard object name across all new Plain workspaces (replacing the older Tenant name and deprecated Company object). Under the hood, the GraphQL schema supports both the account operations (upsertAccount, upsertAccountField, addCustomerToAccounts) and the legacy tenant aliases, and still uses tenant:* for API permission scopes.
Try this: Standardize all new scripts on the *Account mutations (upsertAccount, upsertAccountField, addCustomerToAccounts, updateThreadAccount), and grant tenant:create, tenant:edit, tenant:read, tenantField:create, tenantField:update, tenantFieldSchema:read, and customerTenantMembership:create on the machine user key you use for account syncs.