DEV Community: Themesic Interactive

Why your CRM needs an inbox: inside a Perfex CRM email client

Themesic Interactive — Mon, 03 Aug 2026 16:29:01 +0000

Watch a support agent answer one customer email and count the tabs: webmail in one, Perfex CRM in another, and the invoice or ticket they need in a third. Every reply means re-finding the customer record, re-checking the balance, and copy-pasting context between windows. That is the context-switching tax, and busy teams pay it dozens of times a day. A Perfex CRM email client attacks the problem at its root: it puts the inbox inside the CRM, right next to the records the email is actually about.

Full disclosure up front: we are Themesic Interactive, and we build and sell Mailbox, the module this article walks through. It is the number 2 best-seller in our catalog with 1835 sales on CodeCanyon and 4.78/5 from 41 verified CodeCanyon reviews, so read this as a guided tour with the vendor bias declared, not a neutral review.

The context-switching tax, in practice

The tax is not the two seconds a tab switch takes. It is what gets dropped in transit. An email arrives from a client; the agent answers it in webmail and never files it in the CRM, so the next colleague who opens that client's profile sees nothing. A billing question gets a cheerful reply from someone who never noticed the client has an overdue invoice, because the balance was two tabs away.

The common workarounds - BCC-to-CRM addresses, browser extensions - fail the same way: they depend on a human remembering an extra step on every single message. The structural fix is to reverse the direction: instead of pushing individual emails into the CRM, pull the whole inbox in and make the filing automatic.

What a Perfex CRM email client actually changes

Mailbox connects each staff member's own IMAP account to Perfex's admin area. Everyone gets a Gmail-style inbox inside the CRM: threaded conversations with collapsible replies, a split preview pane, archive and snooze, stars and important flags, multi-filter search, bulk actions, and three density settings (Cozy, Comfortable, Compact). Company email is centralized while inboxes stay separate and private - each user signs in with their own profile email address and maps their own Sent, Drafts, Trash, Spam and Archive folders.

The CRM side is where it earns its keep. Open any message and a sender context sidebar shows the whole relationship at a glance: company, open invoices, overdue balance, open tickets and recent conversation history, with a direct link to the customer or lead profile. From the same message you can:

assign it to a customer, so the thread lives on that profile next to invoices, projects and tickets
convert it to a task, with an assignee and a deadline, linked back to the conversation
convert it to a support ticket, tagged, prioritized and routed to the right department
link it to a lead, where a dedicated Conversation tab collects every assigned email into one history
raise an estimate, invoice or proposal in one click, pre-filled for the linked customer or lead

Most of the filing you never do at all. Smart CRM auto-link matches the sender of every incoming message against your records and attaches it to the right customer or lead as it arrives. It is deliberately conservative: only an exact, single, active match is linked; an ambiguous address is left for a human to decide.

Automation: rules, lead capture and follow-ups

The rules engine matches on sender, subject, body or recipient, then acts inside the CRM: link the message to a client or lead, capture a brand-new lead, create a task or a support ticket, assign it to a staff member, snooze it, star it or tag it. Build the workflow once and incoming mail routes itself. Auto lead capture goes a step further: a message from an unknown sender to your sales address becomes a Perfex lead on its own, filed against the original conversation. It is careful about noise - newsletters, no-reply addresses and system notifications are skipped, existing contacts and leads are never duplicated, and a rejected lead is not recreated by the next email.

Two features target dropped conversations. Follow-up reminders let you flag a sent email with a remind-me-if-no-reply timer; if the client answers, the reminder cancels itself, and if they stay silent you get a Perfex notification at the right moment. First-response tracking gives incoming messages Due soon, Overdue or Answered in time badges against a target you set, with automated senders ignored because a newsletter is not a case to answer.

On the compose side there are reusable templates and signature management, saved replies (personal or shared, with merge tags such as {contact_firstname} and {client_company} filled from the email you are answering), a WYSIWYG editor with attachments and inline images, keyboard shortcuts, and Send Later scheduling. Color-coded tags and labels, nested folders and quick-move actions handle triage at volume.

What the sync actually does (developer notes)

Under the hood Mailbox runs on Webklex/php-imap v4.x. By default it performs a one-way sync: unread inbox mail is fetched into Perfex in the background via Perfex's cron, and actions like Star, Trash and Important are stored locally in the database along with attachments. A manual sync endpoint pulls mail on demand. Optionally, per-staff read status sync writes the read state back to your mail server, so opening a message in Perfex marks it read in Gmail or Outlook too.

Each sync mode (unread only versus fetch all) keeps its own checkpoint, so toggling the setting does not skip older messages or re-import already-synced mail. UIDVALIDITY tracking stops mailbox rebuilds and migrations from silently skipping new mail. Message bodies are fetched once per cycle, batch processing covers the initial sync of large inboxes, and database indexes plus full-text search across subject and body (with an automatic fallback on older MySQL versions) keep the list view responsive.

Authentication is OAuth2 for Gmail and Outlook - tokens encrypted and refreshed automatically, Outlook handled through a single Exchange Online resource with SMTP XOAUTH2 sending - and AES-256-CBC encryption where passwords are still used. The module has been through a security audit and hardened on the back of it: staff mail is strictly scoped to its owner across every view and action, email content is sanitized against a strict allowlist, attachments are served through an authenticated download-only endpoint that cannot execute, state-changing actions require POST, and the OAuth flow validates an anti-CSRF state token.

Who benefits, and who does not

The teams that gain the most already live in Perfex all day. Support agents get ticket conversion and first-response badges in the same pane where they read mail. Salespeople get lead linking, auto-captured leads, the Conversation tab, follow-up reminders that cancel themselves, and every linked email written to the lead's native activity feed. Anyone who invoices gets the overdue balance staring at them before they hit reply.

Honest limits: if your team spends its day in Gmail or Outlook and only opens the CRM weekly, moving the inbox into Perfex solves a problem you do not have. The default sync is one-way - beyond the optional read-status write-back, stars and deletions live in Perfex's database, not on your mail server. POP-only accounts are not supported; you need IMAP with SSL/TLS. Only Gmail and Outlook get OAuth2; with any other provider, an account using two-factor authentication needs it disabled before the mail server will accept the connection. A correctly configured Perfex cron is a hard requirement, since fetching happens in the background, and outbound mail goes through Perfex's own outgoing email settings, with sent messages stored in the module's Sent folder.

Key facts

Fact	Detail
Current version	2.3.1 (updated 2026-08-03)
Requires	Perfex CRM, PHP 7.4 or newer, working cron
Mail protocol	IMAP over SSL/TLS (POP not supported)
Authentication	OAuth2 for Gmail and Outlook; AES-256-CBC for stored passwords
Track record	1835 sales on CodeCanyon, 4.78/5 from 41 verified CodeCanyon reviews

Mailbox is a one-time purchase, with a yearly Pro license for teams that want lifetime support.

Links

If you have questions about the sync model, the rules engine, or whether this fits your setup, ask in the comments - we read all of them.

MCP Server for CRM AI Agents: Design Notes From Shipping One in PHP

Themesic Interactive — Mon, 03 Aug 2026 16:22:21 +0000

MCP support went from a niche spec to a standard buyer question faster than most of us expected. If you ship developer-facing software, someone has probably already asked whether Claude, ChatGPT, Cursor or an n8n agent can talk to it, and for most self-hosted products the honest answer is "not safely." We recently shipped a native MCP server for CRM AI agents inside Perfex CRM, a self-hosted PHP application, and this post walks through the design decisions: where the JSON-RPC 2.0 endpoint lives, why we permission-filter 148 tools per API token instead of exposing everything, and why read-only is our default posture. Full disclosure: we build and sell the module discussed here, but the trade-offs apply to anyone embedding MCP in an existing product.

Some context so the constraints make sense. Our REST API module for Perfex CRM (currently v3.0.3) exposed CRM resources - customers, leads, invoices, projects, tasks, tickets - over plain REST for many releases before v3, with per-token permissions deciding what each integration may touch. Version 3 added the MCP layer on top of that existing surface, and that turned out to be the most important architectural fact of the whole project: we did not design an agent interface from scratch, we projected an already permissioned API into the MCP tool model.

Why the MCP server lives inside the PHP app

The path of least resistance would have been a bridge: a small Node or Python process that speaks MCP on one side and calls the REST API on the other. Many MCP servers for existing products are built this way, and for a hosted SaaS with a single deployment it can be a fine answer.

For self-hosted software it falls apart at distribution. Perfex installs run in environments their owners control and we do not - often shared hosting or a small VPS - and asking an administrator to operate a second long-lived process next to a PHP app is a support burden at best and impossible at worst. A bridge also duplicates state: the API token lives in the CRM, a copy lives in the bridge config, and the permission model has to be re-implemented there or, more commonly, skipped.

So the MCP server is native. The endpoint is POST /api/mcp, speaking JSON-RPC 2.0 over Streamable HTTP, and it ships inside the same module as the REST API, enabled by a toggle in the module's platform settings. This matches PHP's execution model surprisingly well: with Streamable HTTP each JSON-RPC message arrives as an ordinary HTTP POST, so there is no resident process to babysit - just the request-per-execution model PHP has always had. Authentication reuses the existing API tokens (sent in the authtoken header, created in the API Management screen under Setup in the admin area), so an agent presents exactly the credential any integration would, and the same middleware evaluates it.

An MCP server for CRM AI agents should not expose everything

The module defines 148 tools. A naive MCP integration would return all of them from tools/list and enforce permissions only when a tool is called. We rejected that, and it is the decision we would defend hardest.

Instead, tools/list is permission-filtered: a tool appears only if the token behind the request holds the matching permission. Grants are per resource and per verb - Get, Create, Update, Delete - so a token limited to reading invoices produces a short tool list that can read invoices and do nothing else. Granting a capability in the permission editor is the same act that makes its tools visible to an agent.

Three reasons drove this. First, context economics: every tool definition you return is prompt space the client model has to carry, and tool-selection accuracy degrades as the list grows. An agent doing invoice lookups gains nothing from the schemas of tools it can never call. Second, security shape: a capability that is never listed cannot be called, planned around or hallucinated into a multi-step workflow; failing at list time is a stronger invariant than failing at call time. Third, honesty in errors: the expose-everything approach produces agents that confidently attempt forbidden operations, burn a round trip, then improvise around a 403. Filtering the list keeps the model's picture of the world consistent with its actual authority.

Read-only agents as the safety default

LLM agents are probabilistic. A wrong search is a wasted call; a wrong delete is an incident. So our recommended starting posture is a read-only token per agent. The permission editor has a one-click Read-only preset for exactly this reason, alongside per-token request limits, quotas and expiry dates.

The upgrade path is deliberate: run the agent read-only until the workflow proves out, then grant Create or Update on the specific resources it needs, one at a time. For write paths, the API supports an Idempotency-Key header on POST, so a retried create replays the stored response instead of duplicating a record - a property that matters more with agents than with humans, because agents retry enthusiastically. There is also an optional staff-level visibility mode that ties a token to a staff member, scoping data exactly the way the admin panel would for that user.

What agents are actually good at against a CRM

The pattern from our own testing is consistent: agents shine at judgment over small result sets and are a poor fit for repetition.

Good agent tasks look like "find this customer, summarize their open tickets and unpaid invoices, and draft the follow-up", cross-resource questions that would otherwise mean four admin screens, and first-draft record creation where a human reviews before anything is sent. The query itself is fuzzy and the value is synthesis.

Repetitive, fully specified work belongs on the deterministic side of the same module. The OpenAPI spec at GET /api/openapi documents 72 paths and 139 operations for coded integrations, with a reference copy in our examples repository; POST /api/batch executes up to 50 operations in one request; 124 webhook events across 22 event groups push changes out, HMAC-signed and delivered asynchronously with retries; and the n8n community node @themesic/n8n-nodes-perfex-crm covers 19 resources with 108 operations plus a polling trigger, next to native Zapier and Make polling endpoints. The rule of thumb we give customers: if you can write the steps down exactly, use REST, batch or a workflow tool; if the steps require reading and deciding, use the MCP server.

Where this approach is the wrong tool

An honest limits section, because MCP is having a hype moment. Do not point an agent at bulk data migration or high-volume sync - per-step LLM latency and token cost make it strictly worse than a scripted REST client, which is what the batch endpoint is for. Do not give an unattended agent write access to financial records; keep a human in the loop for anything that emails a customer or touches money. And if your needs are purely Zapier-style automation with no natural-language component, the connectors will serve you better than MCP will. The MCP server is a complement to the API, not a replacement for engineering.

Key facts

Item	Detail
Module version	3.0.3 (updated 2026-08-03)
MCP endpoint	POST /api/mcp, JSON-RPC 2.0, Streamable HTTP
Tools	148, permission-filtered per API token
REST surface	72 paths, 139 operations (OpenAPI at GET /api/openapi)
Webhooks	124 events in 22 groups, HMAC-signed, async retries
Batch	POST /api/batch, up to 50 operations
Track record	2,941 sales on CodeCanyon, rated 4.91/5 from 44 verified CodeCanyon reviews

Links

If you are embedding MCP in your own product and made different calls on tool filtering or write access, we would genuinely like to hear how it went - questions and pushback welcome in the comments.

Perfex CRM n8n Automation: 5 Practical Workflows You Can Build Today

Themesic Interactive — Mon, 03 Aug 2026 16:22:18 +0000

Perfex CRM is good at being a CRM and quiet about everything else. Leads land on your website and someone retypes them into the admin panel. Invoices go out and follow-up depends on somebody's memory. Finance wants a payments spreadsheet every Monday. This is a hands-on guide to Perfex CRM n8n automation: five workflows built with the free @themesic/n8n-nodes-perfex-crm community node, covering lead capture, invoice follow-ups, a scheduled export to Google Sheets, webhook-driven ticket routing, and wiring the node into an n8n AI Agent. Full disclosure: we build and sell the REST API module for Perfex CRM that the node talks to. The node itself is free and open source.

Why n8n rather than a hosted automation service? Because both halves of the stack can live on your own servers. Perfex is self-hosted and n8n can be self-hosted, so customer data never passes through a third-party automation cloud, and there are no per-task fees when a busy workflow fires ten thousand times a month. Perfex does not ship a full REST API of its own, so the module supplies one: version 3.0.3 documents 72 paths and 139 operations in an OpenAPI 3.0 spec served at GET /api/openapi, with a reference copy in our examples repo.

Setup: the module, a token, and the community node

Three steps before the fun part.

Install and activate the REST API module in Perfex. Activation takes seconds and there is no core patching.
Create an API token under Setup, then API, then API Management. Permissions are granular per resource (Get, Create, Update, Delete), so give each workflow's token only what it needs. A lead-capture token has no business holding Delete on invoices.
In n8n, open Settings, then Community Nodes, and install @themesic/n8n-nodes-perfex-crm. Add a credential with your Perfex URL and the token; the node authenticates every request with the authtoken header.

The node covers 19 resources with 108 operations plus a polling trigger, which is enough for everything below.

Five Perfex CRM n8n automation workflows

1. Website lead capture

The classic first workflow. An n8n Webhook node receives the POST from your website form, a Set node maps the form fields to lead fields, and the Perfex node creates the lead. Every create response from the API includes a record_id, so you can chain a step that notifies your team with a link to the new lead, or sets source and assignment in the same run. Once this works, the retyping stops for good.

2. New-invoice follow-up

Use the node's polling trigger to watch for new invoices. When one appears, log it, wait the number of days your follow-up policy says, then re-fetch the invoice and check whether it has been paid. If not, send the reminder. The module exposes invoice emailing over the API (POST /api/invoices/{id}/send), so the reminder can come from Perfex itself, or you can send it from n8n's own email nodes. One detail worth knowing: invoice totals are computed server-side from line items, taxes and discounts, so use the amounts the API returns rather than recalculating them in the workflow.

3. Scheduled payments export to Google Sheets

A Schedule trigger fires Monday at 07:00, the Payments resource lists last week's payments using the API's date-range filters (created_after and created_before), and a Google Sheets node appends the rows. Every list endpoint in the API shares a unified toolkit - pagination, sorting, field selection and date-range filtering - so you can pull only the columns the sheet needs instead of full records. Finance gets the same spreadsheet every week and nobody exports anything by hand.

4. Support ticket routing via webhooks

Polling is fine for invoices; tickets deserve push. The module's Webhooks 2.0 catalog covers 124 events across 22 event groups. Create a webhook pointing at an n8n Webhook node URL and subscribe to the ticket events. In the workflow, verify the HMAC signature first - deliveries are signed with a timestamp in the X-Perfex-Signature header for verification and replay protection - and only then trust the payload. A Switch node does the routing: billing keywords assign the ticket to the billing department, urgent phrasing bumps the priority, everything else takes the default lane, each branch calling the node's ticket update operation. Delivery is asynchronous with automatic retries, so a short n8n restart does not silently drop events.

5. The node as a tool for the n8n AI Agent

n8n can hand nodes to its AI Agent as tools, and the Perfex node is no exception. Attach it with a read-mostly token and the agent can answer questions like "which invoices went out last week" or "summarize the open tickets" against live CRM data. Two guardrails we recommend: give the agent its own dedicated token so its permissions are auditable in one place, and start read-only, adding write operations one at a time as trust builds. If you want to go deeper, the module also ships a native MCP server at POST /api/mcp (JSON-RPC 2.0) exposing 148 permission-filtered tools - a second route into the same CRM for AI agents, with the tool list filtered by the same token permissions.

Key facts

Fact	Value
Module version	3.0.3, updated 2026-08-03
Documented API surface	72 paths, 139 operations (OpenAPI 3.0 at GET /api/openapi)
n8n community node	19 resources, 108 operations, plus a polling trigger
Webhooks	124 events in 22 groups, HMAC-signed, async with retries
MCP server	POST /api/mcp, JSON-RPC 2.0, 148 permission-filtered tools
Batch endpoint	POST /api/batch, up to 50 operations per request
Track record	4.91/5 from 44 verified CodeCanyon reviews, 2,941 sales on CodeCanyon

When this is not the right tool

If all you need is a single one-way push - a nightly script that inserts leads from a CSV, say - a short script against the API directly is simpler than operating an n8n instance, and the examples repo, which also carries a reference copy of the OpenAPI spec, is the place to start for direct calls. The module assumes you are comfortable with REST basics; if tokens and JSON payloads are unfamiliar territory, budget for setup help. Operationally: asynchronous webhook delivery works best with a cron job on the Perfex host (there is an admin-load fallback, but a queue that only drains when someone opens the admin panel is not what you want under ticket routing), batch calls cap at 50 operations per request, and self-hosting n8n means updates and backups are your job, not a vendor's. The module is a paid one-time purchase; the n8n node is free but does nothing without it.

Links

If you build one of these workflows, or get stuck halfway through one, tell us in the comments - we read and answer them.

Automating Perfex CRM with a REST API: webhooks, OpenAPI and MCP for AI agents

Themesic Interactive — Mon, 03 Aug 2026 12:51:25 +0000

Full disclosure up front: we build the module discussed here. This is Themesic Interactive's own writeup of the REST API module for Perfex CRM. Every number below is verifiable - the OpenAPI spec, the Postman collection and copy-paste examples all live in a public GitHub repo linked at the end, and you can regenerate the spec from any installation yourself.

The gap

Perfex CRM is a popular self-hosted PHP CRM. Out of the box it has no REST API: no endpoint to create a lead from your website form, no way for n8n or Zapier to react to a new invoice, nothing an AI agent can call.

The REST API for Perfex CRM module adds that layer: 72 paths and 139 operations over the CRM's entities (customers, contacts, leads, invoices, estimates, proposals, credit notes, payments, projects, tasks, milestones, tickets, contracts, expenses, items, staff, subscriptions, timesheets, calendar, knowledge base, notes), plus webhooks, a batch endpoint and an MCP server. On CodeCanyon it is rated 4.91/5 from 44 verified reviews across 2,941 sales, and v3.0.3 is the release this article uses.

60 seconds to your first request

Install the module, then create a token under Setup > API > API Management in the Perfex admin. Every request authenticates with the authtoken header:

curl -H "authtoken: YOUR_API_TOKEN" \
  "https://your-perfex-url/api/customers?page=1&per_page=25"

Creating a lead from anywhere (a landing page handler, a cron job, a chatbot):

curl -X POST "https://your-perfex-url/api/leads" \
  -H "authtoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "source": "2", "status": "1", "email": "jane@example.com"}'

List endpoints take opt-in modifiers, so you only pull what you need:

GET /api/invoices?fields=id,total,status&sort=-date
GET /api/customers?created_after=2026-01-01&created_before=2026-06-30
GET /api/leads/search/acme

Writes support an Idempotency-Key header for safe retries, and responses carry X-RateLimit-* headers so your integration can back off politely.

Webhooks instead of polling

Since v3.0 the module ships 124 webhook events across 22 event groups, managed entirely over REST:

POST /api/webhooks              # subscribe a URL to events
GET  /api/webhooks/events       # list all 124 available events
POST /api/webhooks/{id}/toggle  # pause and resume
GET  /api/webhooks/{id}/logs    # delivery history for debugging

Deliveries are asynchronous with retries, requests are HMAC-signed so your receiver can authenticate the payload, and outbound URLs go through SSRF protection. For polling-based tools (Zapier, Make, n8n's trigger nodes) there are ready-made polling endpoints as well, and a POST /api/batch endpoint runs up to 50 operations in one request.

The whole API as one file: OpenAPI

The module describes its entire surface as an OpenAPI 3.0 document, generated live by the installation itself so it always matches the installed version:

curl -H "authtoken: YOUR_API_TOKEN" \
  https://your-perfex-url/api/openapi -o perfex-rest-api.openapi.json

Import that file into Postman, Insomnia or Stoplight and every endpoint, parameter and response shape appears ready to call. Feed it to openapi-generator for typed clients in PHP, Python or TypeScript. A reference copy exported from v3.0.3 is committed in the examples repo if you want to inspect it before installing anything.

MCP: letting AI agents work the CRM

The part we get the most questions about. v3.0 added a native Model Context Protocol (MCP) server at POST /api/mcp (JSON-RPC 2.0). It exposes 148 CRM tools - create invoice, update lead, search customers, log a payment - to Claude Desktop, Cursor, n8n AI Agent nodes and any other MCP client.

The important design decision: tools are permission-filtered. The MCP server only exposes the operations the API token is allowed to perform, so an agent connected with a read-only token physically cannot write to the CRM. Setup for specific clients is documented in the repo's MCP guide.

If you use n8n, there is also a dedicated community node package: n8n-nodes-perfex-crm.

The numbers, in one place

What	Figure
REST surface	72 paths, 139 operations (OpenAPI 3.0)
Webhooks	124 events, HMAC-signed, async with retries
MCP tools for AI agents	148, permission-filtered
Batch	up to 50 operations per request
Automation	native n8n, Zapier, Make polling endpoints
Track record	4.91/5 from 44 verified CodeCanyon reviews, 2,941 sales