How to use MyCRM.

Find a contact #

The box in the top bar reads “Search contacts by name or email… (Enter)”. Type an email address and press Enter and you jump straight to that person's 360 page; if there is no match you get the toast “No contact with email <what you typed>” and land on the contact list pre-filtered by that text. Type anything else and you land on the contact list with the search applied.

That top-bar box only ever searches contacts — there is no cross-object search. Inside the contact list, the search box searches name, email and company_name, case-insensitively, as “contains”.

Read the header #

Line one is the name, the lifecycle-stage pill, the health-score chip, and — when set — a red DO NOT CONTACT badge and a marketing: <value> badge. Line two is email, phone, title and company, then the product chips. The facts strip underneath shows Last seen, Next expiry, Total spent, Open tickets, Lead score, Source and Created; dates are relative (“3d ago”, “in 2mo”) and hovering shows the exact timestamp. Then Identities: and one pill per identity, written as kind: value.

On the right sit the Owner picker and the buttons: Log activity, Note, Task, Deal, then Refresh, Recompute, Merge into this contact and Delete.

The eleven tabs #

In order: Timeline, About, Entitlements, Activations, Tickets, Deals, Tasks, Notes, Activities, Consents, Feature requests. Every tab except Timeline and About carries a count badge. Each related tab has an Open in list link, and Deals, Tasks, Notes, Activities and Consents also have a New button. An empty tab says so plainly, e.g. “No tickets for this contact.”

The Timeline tab puts the event list on the left and, on the right, the Consent & deliverability panel, the Lifecycle and Signals field sections, and an Open tasks panel when a task is still open. The About tab is every field section: About, Lifecycle, Signals, Consent, Attribution, Address.

The count badges are capped at 100. The 360 fetches at most 100 related records per object, so a contact with 300 tickets shows “100”. Use Open in list for the real total. (The Open tickets figure in the header is separate; it is derived from up to 500 ticket records.)

The timeline #

Events are newest first, grouped under a day heading. Each row shows the title, the relative time, the raw event type in a chip — purchase.renewal, activation.created, ticket.message.in, email.bounced, form.submitted and so on — the actor if one is known, and “via <source>” when the source is not the UI.

A contact's timeline loads the newest 50 events and Load older events pulls 50 more per click. On a non-contact record the panel loads 30 at a time. A contact's timeline is keyed on the contact, so it shows everything MyCRM knows about the person — purchases, heartbeats, tickets, web visits, email bounces — not only what was done inside the CRM. Events carry a dedupe key, so a connector replaying the same data does not duplicate rows.

Actions taken in the CRM write fixed titles: “Logged <type>: <name>”, “Note: <name>”, “Task created: <name>”, “Task done: <name>”, “Deal opened: <name>”, “Deal <name> moved to <stage>”, “Lifecycle stage → <stage>”. The actor is the user's name, or api-key:<key name>, or system.

Which numbers are derived, and when they refresh #

Several header figures are calculated, not typed. Knowing the rules stops the “that number looks wrong” conversation.

lifecycle_stage

A purchase plus at least one still-active entitlement makes a customer, and renewal_due if the earliest upcoming expiry is 60 days or less away. A purchase with nothing active is churned. No purchase but at least one activation is activated. Otherwise lead. An entitlement with no expiry counts as active.

health_score

0–100. +40 seen in the last 7 days, +30 within 30, +15 within 90; +30 if any entitlement is active; −10 if the next expiry is 30 days or less away; −20 if there was a purchase but nothing is active now; −10 per open ticket, capped at −30; +2 per event in the last 30 days, capped at +20; +10 for an activation with no purchase. The chip is green at 70 and above, amber at 40, red below.

products

The sorted, de-duplicated set of product codes across the contact's entitlements and activations.

next_expiry_at

The earliest entitlement expiry that has not yet passed. Already-expired entitlements do not count.

total_spent_cents

The plain sum of entitlement amounts. Subscriptions are never added in — a subscription's recurring amount is informational only.

open_tickets

Tickets whose status is set and is not closed, resolved or done.

first/last seen

The oldest and newest of: entitlement purchase dates, activation last-seen and verified dates, ticket opened and last-message dates, and the most recent event.

Entitlements flagged as Stripe test mode are skipped entirely: they contribute nothing to products, money, expiry, last purchase or last seen.

Lifecycle stage is editable by hand, but recompute may overwrite it. It will overwrite an empty stage, lead, trial, activated, customer, renewal_due and churned. It leaves visitor and won_back alone — those two you can only set by hand — except that a real purchase moves visitor on, while won_back sticks even then. A contact on trial is never demoted back to bare lead.

Edit a field #

Click any value. An editable field says “Click to edit”, an empty one “Click to set”. Type, then press Enter or click away to save; Escape cancels. Long text, JSON, multi-picklist and lookup fields get explicit Save and Cancel buttons instead. Read-only fields carry a small ro marker and cannot be clicked; formula fields carry ƒ. A refusal raises the toast “Could not save <Field label>: <reason>” and shows the reason in red under the field.

Read-only on a contact means: products, first seen, last seen, last purchase, next expiry, total spent, lead score, health score, open tickets, email suppressed, suppressed because, suppressed at.

Merge two duplicate contacts #

1. Open the contact you want to keep. The record you have open always wins.
2. Click Merge into this contact.
3. Under “Contact to merge in (will be removed)”, search by name, email or company and pick the duplicate. A preview line appears.
4. Click Merge and delete the other contact. A toast confirms “Contacts merged”.

What happens: the winner's non-empty values are kept and its empty fields are filled from the loser; the winner's name and email are never overwritten; tags and products are unioned; every identity, every event and every lookup pointing at the loser is repointed at the winner; the loser's email becomes an extra identity on the winner; the loser is soft-deleted; a contact.merged event is written; and the aggregates are recomputed.

Identities #

The identity pills are display-only. Identities are created by the system, never by hand: an email identity whenever a contact is created or updated with an address, machine ids by the commerce-backend connector, Stripe customer ids by the Stripe connector. Email identities are trimmed and lowercased; other kinds are only trimmed. In practice you will see three kinds: email, machine_id and stripe_customer.

Companies #

Companies live at /o/company and open on the generic record page. New company takes Name (required), Domain, Website, Industry, Employees, Phone, Tags and Notes. The right-hand Related area lists one collapsible group per object that points at companies — Contacts, Deals, Tasks, Notes, Activities — each showing up to 50 rows with a View all link when there are more, and a New button that pre-fills the company.

To attach a contact to a company, edit the contact's Company field in the About section and pick the company.

Two more things worth knowing everywhere: contact email is unique, so two live contacts cannot share an address; and money is always formatted as USD, whatever a field's currency setting says. Deleting a contact is a soft delete — “the contact is soft-deleted and disappears from lists”.

Pipeline #

The Pipeline page renders deals as a board grouped by stage. Drag a card to move a deal between stages; each card also carries a stage box, which does the same thing from the keyboard. A read-only user sees the board but cannot drag and has no stage box.

A deal's stage is not a field you type over on the record page — it moves through the board, and the record endpoint guards it. Every move writes “Deal <name> moved to <stage>” to the timeline.

The two guards on a move

Two moves are refused until you supply something the deal is missing:

• Into a won stage, the deal needs an amount above zero. The server answers a won deal needs an amount above zero.
• Into a lost stage, the deal needs a lost reason. The server answers a lost deal needs a reason.

Neither is a dead end. The board catches the refusal and opens a dialog headed Move “<deal>” to <stage> that says “The server refused this move until one more thing is recorded. Nothing has changed yet.” and asks only for what is missing — an Amount box, or a Lost reason picker with an optional Notes field. Fill it in, press Move to <stage>, and the move is retried with that value. Cancel leaves the card where it was. The same two rules apply from the API, where they come back as a 422 naming amount_cents or lost_reason.

The four controls above the board

Get these wrong and the board looks like it is missing deals:

• Closed within — 30 days, 90 days (the default), a year, or no limit. This is the usual answer to “where did our old won deals go?”: won and lost deals that closed more than 90 days ago are simply outside the window. Open deals are never hidden by it.
• View — applies a saved deal view to the board, so the board can be narrowed by the same filters a list uses. The default is “no saved view”.
• The owner controls: Everyone / Mine / Unassigned chips, plus an Owner dropdown for one named person.
• A Search deals box, which narrows the whole board at once.

Two more things about what a column shows. Six stages ship — new, qualified, proposal, negotiation, won, lost — and a deal whose stage is empty, or is a value no longer in the picklist, lands in an extra (none) column. You cannot drop a card into (none); move it to a real stage to empty that column. And each column shows a page of cards — 50 by default — not all of them: the count and the money total in the column header are for everything that matched, and a column with more says “N more not shown” with a link that opens that stage as a list. A column too large to total exactly reads “≥ $X” rather than under-reporting.

Note that a saved view declared as a board — the shipped Team pipeline is one — still renders as an ordinary table when you open it from the deals list. The board is the Pipeline page.

Task inbox #

The Inbox is your open work in five buckets, one panel each, each with a count and the product's own one-line description of what falls into it:

Overdue

“Due before now — a 9am call at 2pm is late”

Today

“Due between now and midnight UTC”

This week

“The following six days”

Later

“Beyond this week, plus tasks with no due date”

Unassigned

“Open tasks nobody owns — the pile this inbox exists to drain”

The four dated buckets each hold a task exactly once. Unassigned deliberately overlaps them — an unowned overdue task is in both — which is why it is not added into the count in the page heading. Buckets are cut against UTC, and the subtitle names the moment they were computed. A bucket with more tasks than the page shows says so at the bottom.

Which inbox you are reading is set by the Mine / Everyone chips and the Or a teammate dropdown.

Quick-add speaks exactly two tokens

The box at the top of the page carries a worked example as its placeholder: Call Ada about the renewal due:tomorrow !high. Everything you type is the task name except two kinds of token:

• A due date: due:today, due:tomorrow, due:+3d, due:2026-09-01.
• A priority: !low, !normal, !high, !urgent.

The new task goes to whoever the chips are pointing at: yourself on Mine, the named person from the dropdown, or nobody at all on Everyone, which leaves it in the unassigned pile on purpose.

Done, Snooze, Reopen

Every row carries Done and Snooze; a task already done carries Reopen, which puts it back on the queue. Completing a task writes “Task done: <name>” to the timeline; like deal stage, a task's status and completion time are guarded on the record endpoint rather than edited as plain fields. Row checkboxes plus Complete selected tick off a page of them at once — the one bulk action in the product that is not owner assignment.

Snooze offers tomorrow, +3d, +7d, +14d or a date you pick, and it is capped at five. A sixth is refused outright: past the cap the task has to be re-dated, cancelled or done. A snoozed task carries a snoozed N× badge, and the first snooze records what the task was originally due, so the badge answers “how long has this been pushed” rather than only “when was it last pushed”. A completed or cancelled task cannot be snoozed at all — reopen it first.

Three shipped task views cover the same ground from the list side: My open tasks, Overdue tasks and Unassigned tasks. On a contact's Timeline tab, an Open tasks panel appears whenever that person has a task still open.

Quick-create buttons on a contact — Log activity, Note, Task, Deal — are the fastest way to put work on the board without leaving the record.

Create one #

New form asks for: Name, Slug, Kind, Enabled, Allowed origins, Lead source recorded, Consent checkbox text, Consent required to submit, Create a follow-up task, Success message, Redirect after submit. Kind is pre-set to lead; Enabled and Create a follow-up task are pre-ticked. The slug takes lowercase letters, digits, - and _, and becomes the public URL.

Everything else — field mapping, Required fields, Tags applied, Notify the owner, Notify this address, Submissions per hour per IP, Require Turnstile, Product — is edited afterwards by clicking the form's name, which opens its record page.

Get it onto your site #

Embed opens automatically after you create a form, and is on every row. Three tiles show Submissions, Slug (locked or still changeable) and Allowed origins. Under “Paste this into the page”, press Copy snippet and paste the block into your HTML — it is a plain <form> plus a <script src=…> include. The URLs block lists the submit URL, the script include, the hosted page and the thanks page.

The snippet works with JavaScript switched off: the browser posts the plain form and lands on the thanks page. The script only removes that page navigation. If you would rather not embed anything, link people to the hosted page URL instead — it is the same address as the submit URL, rendering the form on GET and accepting it on POST.

“Fields the form posts” lists exactly what the snippet renders. For a lead form: Email (required), Name, Company, “How can we help?”. For a feedback form: the 0–10 recommendation score, “What could we do better?”, and an optional email.

Allowed origins — the setting that loses leads #

Add one entry per site that hosts the form, matching scheme and host exactly: https://www.example.com, no path, no trailing slash. Empty means same-origin only. * allows everything.

Before you trust a form, use Embed → Check configuration. “No problems found.” means it is clean; otherwise each line is labelled error or warning against the field it concerns. Fix every error — those are the ones that lose data. Common warnings are worth reading too: “the form is disabled: submissions are accepted and silently discarded”, “Turnstile is requested but no secret is configured on this server, so it is not enforced”, and “notifications are configured but no mailer is wired on this server; submissions are still captured”.

What the consent checkbox records #

Put your wording in Consent checkbox text — it is recorded verbatim as evidence — and tick Consent required to submit if the form must not proceed without it. On a ticked submission MyCRM writes a consent record named “Marketing consent — <email>”, purpose marketing, status granted, source form:<slug>, with an evidence block holding your wording, the form name and slug, the page URL, the time, and a keyed hash of the client (the address itself is not stored). Only then is the contact's own Marketing consent set to granted.

Values that count as ticked: on, yes, y, true, 1, granted, checked. Anything else leaves consent unknown, which the send gate treats as a no.

A ticked box cannot un-revoke. If that contact previously revoked marketing consent they stay revoked; the audit record is still written, named “Marketing consent NOT APPLIED (previously revoked)” with a line explaining that a public form may not grant it again. A public form can also never write marketing consent directly, consent date, do-not-contact, lifecycle stage, lead score, owner, tags, lead source or the suppression fields, whatever the field mapping says.

What the visitor sees #

On success with JavaScript, the form is replaced by your Success message; the defaults are “Thanks — we have your details and will be in touch.” for a lead form and “Thanks — your feedback is with the team.” for feedback. Without JavaScript it is a redirect to your Redirect after submit, or to the thanks page.

Only two kinds of thing are ever shown as a problem. Something the visitor must fix appears by the form: “An email address is required.”, “That email address does not look right.”, “<Field> is required.”, “Please tick the box to continue.”, “Please give a score between 0 and 10.” And a genuine server fault says “we could not record that just now — please try again”. A refused submission consumes nothing: fixing it and pressing Send again counts as a first attempt.

Telling somebody a lead arrived #

Two settings on the form record can trigger it:

• Notify this address — one fixed address, typed on the form. Useful for a shared sales inbox.
• Notify the owner — a tick-box. The server resolves the form record's own Owner to that person's email address, so re-assigning the form re-points the notification with it. A form with the box ticked and no owner — or an owner whose account has been switched off — notifies nobody.

One submission produces at most one notification, so if you set both, the fixed address wins and the owner is not written to as well. Both routes really do send, and both go through the same send gate as every other message MyCRM produces. If the destination address is suppressed the notification is skipped and the reason goes to the server log — a notification is never the thing that mails a dead address. Nothing about that touches the submission itself: the contact, the consent record and the follow-up task are written either way.

One case where nothing is delivered: a server built without a mail path at all. Embed → Check configuration says so as a warning — “notifications are configured but no mailer is wired on this server; submissions are still captured” — and a bad address in Notify this address is reported there as an error rather than being discovered when a lead goes missing.

The limits that are built in #

• Body capped at 8 KiB. Longer is “That submission is too long. Please shorten it and send it again.” A body that cannot be read at all — a malformed or truncated post — is “We could not read that submission. Please try again.”
• 20 submissions per hour per IP per form by default, overridable per form; and 5 per hour for one email address across every IP it uses. Both are stored as keyed hashes, so no address or IP is kept in the rate table.
• A submission faster than 2 seconds after the form was rendered is dropped. A fill token expires 24 hours after render.
• An identical payload from the same client inside 10 minutes is written once — that is the double-clicked Send. Two different people submitting the same answers are still two submissions.
• The honeypot input is named website_url and is rendered off-screen with the label “Leave this field empty”. Any value in it drops the submission.
• First-touch attribution (utm parameters, landing page, referrer, first-touch time) is recorded once and only ever fills a blank field — it never overwrites something a human typed.

A lead form with a follow-up task opens “Follow up: <name or email>” due in 24 hours.

Feedback forms #

Set Kind to feedback. The posted fields are score, comment and an optional email, with sensible aliases understood without configuration. Each submission creates a feedback record with channel form. Scores are range-checked — NPS 0–10, CSAT 1–5 — and out of range is a visible error, not a silent drop. NPS bands are 0–6 detractor, 7–8 passive, 9–10 promoter; a detractor or unhappy score opens a high-priority “Call back” task due in 24 hours, anything else a “Review feedback” task due in 72.

A feedback form never creates a contact. If the address matches someone you already have, the response is linked to them; otherwise it is stored anonymously. That is why consent wording on a feedback form raises a warning — there is nothing for it to attach to.

Add one #

Add connector asks for a Kind — the three are “iOwn commerce backend (api.iownsoftware.com)”, “SendGrid (email deliverability)” and “Stripe (read-only retention state)” — an optional Name, an optional sync interval in minutes, and then the kind's configuration fields. Required fields carry a red asterisk; secrets are password inputs. The Streams chips list what the kind pulls; they are informational and you cannot pick a subset.

There is no enabled checkbox in the Add form and no “Test connection” button. If you are not ready for it to sync, add it and immediately turn the Enabled toggle off in the table row. To check credentials, save and press Run now.

iOwn commerce backend #

Needs a Base URL (pre-filled) and a CRM partner key — a key configured on the commerce backend, not something MyCRM generates. Page size defaults to 500; it syncs every 5 minutes.

This is the connector that owns money. It mirrors ten streams — products, customers, purchases, activations, trials, captures, tickets, web events, blocked and feature requests — into Contacts, Products, Entitlements, Activations, Tickets, Feature requests and the timeline. Entitlements are what the renewal plays work from, so nothing in the renewal engine happens until this connector is running.

Stripe #

Needs a Restricted API key starting rk_live_ or rk_test_, and a dated Stripe-Version such as 2025-03-31.basil — there is no default and blank fails. Create the key in Stripe under Developers → API keys → Restricted keys, with read scopes for Customers, Charges, Refunds, Disputes, Subscriptions, Invoices, Products, Prices and Checkout Sessions, and nothing else. Include test-mode objects is off by default. Page size defaults to 100, which is also Stripe's maximum; it syncs every 15 minutes.

Two things people get wrong. A normal secret key (sk_…) is refused outright, before any network call — the connector is read-only by construction and will not accept full-access credentials. And it creates zero entitlements and never touches revenue; purchases and money come from the commerce backend. What it writes is the Subscription object — status, current period end, cancel-at-period-end, trial end, Payment failing, last payment failure — plus refunds and disputes on the timeline. Payment failing is exactly what the dunning_followup play triggers on.

Configure an rk_test_ key while test-mode objects are off and the run succeeds while mirroring nothing.

SendGrid #

None of its fields are required, because a webhook-only setup is supported. The Event webhook verification key is the base64 public key from SendGrid's Settings → Mail Settings → Signed Event Webhook; without it the webhook refuses every batch. Comma-separate two keys to rotate without an outage. The API key is optional and only needed for the suppression pull — read access to Suppressions is enough. Pull existing suppression lists is on by default; it polls bounces, blocks, spam reports and unsubscribes, which is both how a fresh install inherits SendGrid's history and how a missed webhook batch gets repaired. It polls every 15 minutes.

Then point SendGrid at MyCRM. The webhook URL is your origin plus /webhooks/sendgrid/<connector id>.

Run, edit, reset, delete #

Click a connector's name, or Details on its row. The window shows four tiles — Enabled, Interval, Last run, Last status — then Configuration, Run history and Cursors. The Enabled tile is read-only; the actual switch is the toggle in the table row, and that is how you pause a connector without deleting it.

• Run now syncs immediately. It is synchronous and can take up to 4 minutes; long backfills continue on the next scheduled tick because cursors are saved per page.
• Edit in the Configuration panel changes the name, the interval or any config field. Masked secrets (••••••••) are kept unless you type a new value; clearing a secret field deletes it.
• Reset cursors clears every stream's position, so the next run backfills from the beginning. It is all-or-nothing in the UI; resetting a single stream is API-only.
• Delete connector stops the syncs and keeps the synced records.

Is it healthy? #

The table's Status column shows a green ok or a red error pill with the message truncated underneath; Last run shows a relative time or a grey never. Details gives the whole picture: the Last status tile, then Run history — the 20 most recent runs, each with start time, status, duration and stat chips — then Cursors, which shows how far each stream has got as raw JSON. Runs older than 30 days are deleted automatically.

For SendGrid, the Cursors panel is also the webhook's health report. A stream named webhook_last carries the time and counts of the last accepted batch. A stream named webhook_error appears when batches are being refused for a reason you must fix — a missing signing key, or a host clock more than five minutes out.

Add a custom field #

Pick an object on the left, click Add field, then fill in: API name (lowercase letters, digits and underscores, starting with a letter), Label, Type, Section, plus whatever the type needs — “Values (comma separated)” for a picklist, “Target object” for a lookup, “Formula” and “Result type” for a formula. Optionally tick Required and Indexed (faster filters). The field appears immediately in filters, the create modal and the record page.

The types on offer are text, long text, number, currency, bool, date, datetime, picklist, multi-picklist, lookup, email, phone, URL, JSON, formula and tags. Currency is stored as integer cents. Text fields are limited to 4,000 characters — use long text for prose. Dates are YYYY-MM-DD and datetimes are RFC3339 in UTC.

Formula fields are computed when the record is read, are never stored, and cannot be sorted or filtered on. The two that ship on a contact are Days since seen and Days to expiry.

An API name cannot collide with the record's own columns: id, object, created_at, updated_at, deleted_at, owner_id, source, external_id, tenant_id.

Delete a custom field #

The trash button at the end of the row (“Delete custom field”) — standard rows have no button. The confirmation warns that stored values become inaccessible: only the definition is deleted, the values stay in the records and simply become unreachable. Saved views that named the field quietly drop the column rather than breaking.

Add a custom object #

Add object takes an API name in snake_case, a Label, a Plural and a Description. “A required name text field is created automatically. Add more fields afterwards.” The object appears in the sidebar under Objects, lists at /o/<api_name>, and its records open at /r/<id>. New objects are created with the timeline enabled and a single list column.

The Add-field form also cannot set unique, hidden, read-only or a default value; those exist in the data model but have no UI.

Signing in #

too many requests; try again later

More than 6 sign-in links requested from one IP in 15 minutes.

Do: wait for the window to pass. If a whole office shares one outbound address, it shares one budget of six.

this sign-in link is invalid or has expired

A link older than 20 minutes, a link already used once, or a link from a different deployment.

Do: request a new one and use the newest email. Older ones stay dead.

could not send the sign-in email; ask an admin to check the mail settings

The mail provider rejected the message.

Do: an operator checks the SendGrid key and the from-address, and looks for the log line magic link mail to … failed: ….

That code was not accepted. Try again.

A wrong 6-digit code — or the 10-minute window between clicking the link and entering the code ran out, which produces exactly the same message.

Do: retype the current code once. If it fails again, press Start over and request a fresh link.

Code not accepted — check your authenticator app and try again.

Enabling two-factor with a code that does not match the freshly generated secret.

Do: confirm the app scanned the QR on this page rather than an older entry, and that the phone's clock is set automatically.

unauthorized

No credentials, an expired session, a revoked API key, or a disabled account. In the browser you are simply sent to the login screen.

Do: sign in again. If it repeats instantly, an admin has switched the account off.

totp required

A half-finished session — link redeemed, code never entered — used against an endpoint.

Do: finish the two-factor step, or start over from /login.

Signed in with an API key — no profile to show.

The Profile page opened by a key rather than a person. Nothing is wrong.

Permissions #

admin access required · Admin access required.

A member or read-only user, or a read/write key, reaching a Settings area: users, API keys, connectors, playbooks, object or field changes. The page version replaces the whole body and does not redirect.

Do: have an admin do it, or have them change your role on the Users page and reload. For integrations, mint a key with the admin scope.

write access required

A read-only user or a read-scoped key attempting a create, update or delete. The UI hides these controls from read-only users, so in practice this reaches integrations.

Do: use a member or admin account, or a write-scoped key.

missing X-Requested-With header

A cookie-authenticated write without X-Requested-With: MyCRM — something other than the MyCRM UI reusing the browser's session cookie.

Do: authenticate the integration with Authorization: Bearer mycrm_… instead. The header requirement does not apply to Bearer calls.

you cannot disable or demote yourself

An admin trying to switch off their own account or drop their own role. The UI disables both controls on your own row, so this is reachable only through the API.

Do: ask another admin. This exists so a deployment can never end up with zero admins.

views: @me needs a signed-in user (API keys must filter by an explicit owner_id)

An integration ran a view or filter using @me. Keys have no user identity.

Do: filter by an explicit owner, or use a view that does not use the token.

Records and fields #

a record with the same unique value already exists

Another live contact already has that email address.

Do: search for the address in the top bar — it jumps straight to the contact — and edit or merge into that record instead.

field is read-only

Writing a system-maintained field: products, first and last seen, last purchase, next expiry, total spent, health score, open tickets, lead score, the suppression fields.

Do: change the underlying entitlement, activation or ticket data, then press Recompute on the contact.

computed field is read-only

Supplying a value for a formula field when creating a record.

Do: leave it out. It is calculated when the record is read.

a won deal needs an amount above zero

Moving a deal into a won stage while its amount is empty or zero. A won deal with no money in it is a number nobody can forecast from, so the move is refused.

Do: on the Pipeline board this opens a dialog by itself — type the amount and press Move to won. From the API, re-send the stage move with amount_cents.

a lost deal needs a reason

Moving a deal into a lost stage with no lost reason recorded.

Do: the board asks for it: pick a Lost reason, add optional notes, press Move to lost. From the API, re-send the move with lost_reason.

must be one of unknown, granted, denied, revoked

A picklist value outside its list — the same shape of message appears for lifecycle stage and every other picklist.

invalid email

An address that will not parse, or one containing a space or angle brackets.

Do: enter a bare address. No display name, no brackets.

too long (max 4000)

A text field over 4,000 characters.

Do: shorten it, or use a long-text field for prose.

this record is mirrored from <source> and cannot be deleted here — deleting it would stop that connector from ever syncing it again. Remove it at the source, or disable the connector.

Deleting an entitlement, activation, ticket, subscription, product or feature request that a connector created.

Do: delete it in the system of record and let the connector sync, or turn the connector off. Contacts are not mirrored this way and can be deleted.

contacts: cannot merge a contact into itself · contacts: merge only supports contacts

Both sides of a merge are the same record, or one of them is not a contact.

Do: pick a different duplicate. There is no merge for companies or any other object — re-point the related records by hand and delete the duplicate.

meta: invalid field api_name "<name>"

An API name with uppercase, a leading digit, spaces, or one that collides with a reserved column such as id or owner_id.

Do: use snake_case starting with a letter.

meta: not found: field <object>.<field> (or it is standard)

Deleting a field that does not exist, or one that ships as standard.

Do: standard fields cannot be removed. Leave the value empty, or add your own field alongside.

Lists, views and assignment #

records: cannot filter on computed field "days_since_seen"

You picked a computed field in the filter builder. The builder offers them; the server refuses them.

Do: remove that row and filter on the stored field instead — Last seen, not Days since seen.

records: unknown order field "<field>"

A shared or bookmarked URL sorts by a field the object no longer has.

Do: click any column heading to re-sort, or strip order_by= from the URL.

no such view

A ?view= link pointing at a deleted view, or at somebody else's private view — those are reported as missing, never as forbidden.

Do: pick a view from the dropdown. If a colleague meant to share it, ask them to open it, click Rename and tick Share with the whole team.

views: a view with that name already exists for this object

The name is taken in the same scope — another shared view of that name, or another private view of your own. A private view and a shared view can happily share a name; the uniqueness rule is per object and per owner, with shared views all counting as one ownerless scope.

Do: qualify the name, e.g. “Renewals — BJ”.

owner_id is not a user of this tenant who can be assigned records

The person has since been disabled or moved to read-only, and the picker was loaded before that.

Do: reload so the roster refreshes. In a bulk assign this refuses the whole batch, because the owner is wrong for every row.

not found · record is a <object>, not a <object>

In the Record/Reason table after a bulk assign: rows deleted by someone else while you had them selected, or an id from a different object.

Do: close the dialog, let the list reload, re-select and assign again. The rows that succeeded have already moved.

Unknown object “<name>”.

A stale bookmark to an object this server does not have.

Do: pick the object from the sidebar. Admins can check what exists at Settings → Objects.

Forms #

Sorry, that did not go through.

The embedded script's request failed — commonly because the page's origin is not in Allowed origins.

Do: add the exact origin (scheme and host, no path) to the form record, then re-run Embed → Check configuration.

no such form

The slug in the posted action URL does not exist.

Do: copy the submit URL again from Settings → Forms → Embed.

this form has already received submissions, so its slug is part of a public URL that other sites are using — create a new form instead of renaming this one

Editing the slug on a form with submissions.

Do: leave it alone and create a new form with the slug you want, then swap the snippet on your site.

we could not record that just now — please try again

A genuine server fault while writing a submission. This is the only failure not dressed up as success, precisely so the lead is not silently lost.

Do: retry, and check the server log.

Hosted forms are not enabled on this server — the /f/ endpoints are not mounted, so there is no embed snippet or public URL. The form record is still here and will work as soon as the service is wired.

The build never mounted the public forms surface.

Do: nothing in the UI — the deployment has to wire the service. The form record is safe.

And the failure with no message at all: leads that stop arriving. Check Allowed origins first, then whether the form is enabled, then the per-IP and per-email rate limits, then the server log for dropped submission.

CSV import #

imports: this file maps a consent column, which needs an explicit affirmation from an admin session: <column names>

A dry run on a file that maps a consent column, without the affirmation.

Do: use the affirmation panel — tick the confirmation, describe where the consent came from, press Record the affirmation — or set that column to “ignore this column” and import the rest.

This import already failed the consent check, and a failed job cannot be re-mapped. Start another import and affirm before the dry run.

You tried the dry run first and the job is now in error.

Do: Start another import, re-upload, affirm, then dry-run.

The preview went stale — the job or its mapping changed since that dry run. Run the dry run again and commit the fresh result.

The mapping changed, or the database moved under the approved preview.

Do: the wizard puts you back on Columns. Run the dry run again, read the new numbers, commit that.

imports: not valid UTF-8 — … re-save the file as UTF-8 (or UTF-16 with a byte-order mark)

A legacy encoding — Windows-1252 curly quotes are the usual culprit.

Do: in Excel, Save As → “CSV UTF-8”, then upload again. The offset in the message tells you where to look.

imports: 100001 data rows exceeds the 100000-row limit — split the file

Too many rows, or too many bytes for the 10 MiB cap.

Do: split the spreadsheet. Each part gets its own batch tag and its own undo.

consent for this contact was revoked; an import may not grant it again (the person has to)

A row would set marketing consent back to granted on somebody who revoked it. A hard row error, in the dry run as well as the commit.

Do: remove the row or the column. If they genuinely re-opted in, record it from a form with a ticked box.

this contact is marked do not contact; an import may not clear that flag

A row would clear do-not-contact.

Do: clear the flag on the contact by hand if that is really what you mean. The importer will not.

duplicate email "a@b.c" — row 12 in this file has the same value

Two rows share the matching value, or resolve to the same existing record.

Do: download errors.csv, merge the rows in the spreadsheet, re-upload.

imports: invalid request: this file has no column that can match a row to an existing record…

No unique column is mapped, so every row would create a new record and re-importing an export would duplicate it. Only four fields are unique anywhere in MyCRM — contact email, product code, form slug, suppression email — so every other object hits this unless you name a dedupe field yourself.

Do: map a column that identifies the record. The wizard has no control for choosing one, so otherwise it is an API call.

imports: undoing an import needs an admin session

A non-admin, or a key, called undo.

Do: ask an admin to open the import and press Undo this import.

the commit failed partway and did not finish: <error>

A commit died with records already written. The job is marked partial and the records it wrote are live.

Do: do not re-upload. Have an admin undo the import — the journal names exactly which records landed.

Connectors and playbooks #

connectors: config api_key cannot be unsealed — the master key does not match the one that sealed it; re-enter the secret

The instance's master key changed — a data directory restored from a different install, or a lost key file. Every run now fails before it starts.

Do: Details → Configuration → Edit, retype the secret (do not leave the mask), Save changes. And read the backup note under Self-hosting: running it after the install.

stripe: api_key is a secret key (sk_…) — this connector is read-only and refuses full-access credentials…

A Stripe secret key was pasted into the restricted-key field. It is refused locally, before anything reaches Stripe.

Do: create a restricted key with the nine read-only scopes and paste the rk_ value.

stripe: api_version is required — pin a dated Stripe-Version (e.g. 2025-03-31.basil)

The version field is blank. There is no default.

stripe: forbidden on /v1/disputes — the restricted key is missing a READ scope for this resource

The restricted key was created without one of the required read scopes.

Do: edit the key in Stripe, add read access for the named resource, re-run.

apihub: unauthorized (check partner_key)

The commerce backend rejected the key on the connector's first call, so no stream ran.

Do: re-enter the partner key; it must match what is configured on the commerce backend.

apihub: export not configured on the api (CRM_PARTNER_KEY unset)

The CRM export is not switched on at the other end.

Do: the fix is on the commerce backend, not in MyCRM.

sendgrid: API key rejected (needs read access to Suppressions)

The suppression pull was refused.

Do: issue a key with read access to Suppressions, or clear the field to run webhook-only.

signature verification is not configured

SendGrid is posting events but the verification key is empty or unusable, so every batch is refused. The Cursors panel gains a webhook_error entry.

Do: paste the base64 verification key from SendGrid into the connector and save.

timestamp outside the accepted window

The signature verified but this host's clock is more than five minutes out.

Do: fix time sync on the server. The suppression pull backfills whatever was rejected meanwhile.

invalid signature

A post the configured key cannot verify — a stranger, or a key rotation done without overlap.

Do: if it is your own traffic, put both the old and new keys in the field, comma-separated, until SendGrid has switched over.

unknown connector

The connector id in the webhook URL does not exist, or belongs to a connector of another kind.

Do: get the real id from mycrm connector list and rebuild the URL.

a run is already in progress

A scheduled tick beat you to Run now, or two admins clicked at once.

Do: watch Run history and try again when it finishes.

playbooks: deal guard on renewal_of did not complete (more than 10000 rows for 500 subjects); refusing to plan against a partial guard

A play's safety check could not read all the existing deals or tasks it needed to check against, so it refused to plan anything rather than write over records it could not see.

Do: narrow the window — a lower lead time or lookback — so fewer candidates are in play. The next run retries.

Email health #

no suppression for that address

Release was called for an address with no suppression record.

Do: check the spelling, and check the Released / All filters — it may already have been released.

This server has no form object, so there are no hosted forms to configure. · This server has no suppression object.

The instance's metadata does not include those standard objects.

Do: nothing on those pages will work until the standard objects are seeded on that tenant.

network error — is the server running?

The browser could not reach the server at all. Nothing was sent.

Do: click Retry, or Refresh in the page header, once the connection is back.