Address Book

What it is

The contact directory — everyone the company deals with, whether or not they are a billing customer. Contacts arrive by hand, by CSV, and by mining the mailboxes.

Three tabs: 👤 Contacts (described below), 🚢 Vessel Directory, ⚓ Port Agents.

Who can open it

Any signed-in staff account that is active. Two gates, both in proxy.ts: account status, then the sales.address-book feature grant while FEATURE_GRANULAR_RBAC is on, with the owner bypassing. The same grant covers /port-agents and the pending-contact queue.

Sync IMAP has a second, stricter check of its own: its API requires operator capability or above. Every real staff role clears that; only an account still in pending does not.

Before you start

🔴 "Restore CSV" is a blunt recovery tool, not an importer. It splits each line on commas with no handling of quoted fields. Any value containing a comma — an address, most obviously — shifts every column after it, and the row is imported wrong rather than rejected. The code says as much: "simple split by comma ignoring quotes for basic recovery... a true parser like PapaParse is recommended". Use it only to restore a file this screen exported, and check the result. One field is protected: an obviously junk port value is dropped rather than imported, because that field feeds outreach copy.

⚠️ A failed IMAP sync looks exactly like one that found nothing. Errors are written to the browser console and nowhere else, and a rejected request simply leaves the list unchanged. If "Sync IMAP" appears to do nothing, it may have failed rather than found nothing new.

Contacts the mail sweep declines to file do not appear here. They queue for review — a counted Pending Contacts (N) button appears in the toolbar when any are waiting. See Address Book — Pending.

Every control on the page

Toolbar:

Control	What it does
Search CRM...	Matches name, company, vessel and email.
Pending Contacts (N)	The triage queue. Hidden when the queue is empty, so its absence means nothing to do.
Restore CSV	Uploads a CSV — see the warning above. Reads Uploading... while it runs.
Sync IMAP	Sweeps the mailbox for contacts (the INBOX, 250 messages at a time). Reads Syncing... while it runs.
Export Full CSV	Downloads the whole contact set — not just what is filtered on screen — as A2Z_CRM_Export_<date>.csv.
New Contact	Opens the contact form.

Filter chips — these are the categories the directory is organised by:

Chip	Shows
All Logs	Everything.
Primary Directs	Contacts that have not been merged into another record.
Vessel Bridge	Contacts marked as a vessel master.
Office Pro	Shore contacts with an email address — everyone not a vessel master.
Purchasing	Job titles containing purchasing, purchaser or procurement.
Mgmt	Job titles containing manager, superintendent, director or captain.

⚠️ Purchasing and Mgmt read the job title only. A contact whose title is blank or worded differently — "Buyer", say — falls into neither, however obviously they belong there. Use search when a chip comes up short.

Tabs — 🚢 Vessel Directory and ⚓ Port Agents each load their own screen in place.

New Contact form — fills the contact's details and adds them to the directory.

Per contact — the row opens the contact, and an outreach action starts a message to them carrying their name, company, email, vessel and IMO where known.

What it writes

Action	What it writes
New Contact	Creates the address_book row.
Restore CSV	Inserts one address_book row per CSV line. id and created_at are always regenerated, so a restore adds rows rather than overwriting the originals.
Sync IMAP	POST /api/address-book/sync — files what it can and queues the rest for pending triage.
Export Full CSV	Downloads; writes nothing.

When it goes wrong

Sync IMAP seemed to do nothing. It may have failed silently — nothing on screen distinguishes a failure from an empty result. Try again, and report it if contacts you expect never arrive.

A restored CSV came back with data in the wrong columns. A field contained a comma. The importer does not understand quoted fields; fix the file or re-enter those rows by hand.

A restore created duplicates. It always inserts new rows — it never matches or replaces existing ones.

Purchasing or Mgmt is missing someone obvious. Both match on the job title text only. Set the title, or find them with search.

There is no Pending Contacts button. The queue is empty — or the count failed to load. Open /address-book/pending directly to be sure.

Export gave you more than you filtered. That is intended: the export is the full contact set, not the filtered view.

Related screens

• Address Book — Pending — the triage queue for what the sync would not file.
• Address Book — Directory and Port Agents — the other two tabs.
• Clients — billing customers, which this directory does not create.