Skip to main content

Address Book — Pending

What it is​

The worklist of email addresses the nightly Bridgemail sync found in the mailboxes but would not file on its own. Each row is an address, plus whatever the sync guessed about it — a name, a company, a vessel, a type — and a count of how many times it has been seen.

You decide one thing per row: Approve or Reject.

Three facts about approving are worth knowing before you touch it, because they are what make the screen safe to sweep through:

  • Approving writes to the address book and nowhere else. It never creates a client and never creates a supplier, no matter what the Type column says. The guessed type is kept as a note on the record, not as the record's type.
  • Approving an address that is already in the book only fills its blanks. Name, company and vessel are filled where the existing record is empty. Nothing a person typed is ever overwritten, and the record's entity is never changed.
  • Rejecting deletes nothing. It marks the row rejected and takes it off this list.

About half of what is queued is already in the address book — those rows show IN BOOK, and approving them is the cheap "fill in the blanks" action rather than a new record.

This screen has no Feature ID of its own. The feed that fills it is A2Z-F315 — Bridgemail contact sync, and that feature's row is where the queue is described. If you are looking the screen up in docs/audit/07_MASTER_FEATURE_INVENTORY.md, search for F315, not for the screen name.

Who can open it​

Any signed-in staff account that is active. There is no role check on this screen — it is not restricted to sales, and an operations or accounts login reaches it the same way.

Two gates sit in front of it, both in proxy.ts:

  1. Account status. A signed-in account that is not active is sent back to the login page.
  2. The feature grant sales.address-book, but only while FEATURE_GRANULAR_RBAC is switched on. When it is on and your account has not been granted that feature, opening the page bounces you to the dashboard with ?denied=sales.address-book in the address bar. The owner account bypasses this unconditionally.

sales.address-book is the same grant that covers /address-book and /port-agents — there is no separate grant for the pending queue.

Before you start​

Find it from the Address Book. The link is a button in the Address Book toolbar reading Pending Contacts (N), where N is how many rows are waiting. It is hidden when the queue is empty — and also if the count fails to load — so an absent button means "nothing to do", not "you are in the wrong place". The screen is in no sidebar and no menu; that toolbar button and the URL itself are the only ways in.

Two things to know before sweeping:

  • The junk badges are advice, not a decision. They are worked out from the address alone and they select nothing by themselves.
  • Rejected rows disappear from this screen and there is no way back through it. The list only ever shows what is still pending. There is no "show rejected" control, no undo and no count of what was rejected earlier. If you reject something by mistake, raise it with whoever administers the system rather than trying to re-approve from memory.

Every control on the page​

Filters — four boxes across the top, then a button:

ControlWhat it does
TypeExact match on the sync's guessed type, e.g. CLIENT. Exact, not a search: client in lower case matches nothing. Typing (null) gives the rows the sync left unlabelled.
DomainAddresses ending @ that domain, e.g. msc.com.
Email containsAnywhere in the address, e.g. purchase.
Seen ≥Only rows seen at least that many times. An address that keeps reappearing is more likely to be a real person.
ApplyRuns the filters. Nothing filters until you press it — typing in a box changes nothing on its own — and pressing it returns you to the first page.

Selection and decisions — the row above the table:

ControlWhat it does
"N pending · N selected"The first number is the whole filtered queue, not just this page.
Select pageTicks every row on this page. It reads Clear page once they are all ticked.
Select N junk on pageOnly appears when the page holds rows the junk check flagged. Ticks exactly those.
Approve → address bookFiles every ticked row. Greyed out until something is ticked.
RejectMarks every ticked row rejected. Greyed out until something is ticked.

Ticking is per page and deliberately does not carry. Changing page or pressing Apply clears your selection, so one click can never decide rows you never looked at.

The table — Email, Name, Company, Type, Seen, Status. Name, Company and Type show — when the sync had no value. The Status column carries up to two badges:

BadgeMeaning
MALFORMED EMAILNot a usable address — a mail header stored whole, a display name and address run together, or an empty value.
OWN DOMAINContains a2zship. Our own addresses, and the mistyped versions of them the mining picked up.
ROBOT ADDRESSnoreply, donotreply, mailer-daemon, postmaster, bounce and the like. It can send but never reads.
IN BOOKThe address is already in the address book. Approving fills its blanks rather than creating a record.

Paging — Previous, a "1–100 of N" position, and Next, at the bottom. 100 rows a page, and the paging row only appears when more than 100 match.

Messages you will see:

  • Loading queue… while a page is fetching.
  • Nothing pending under these filters. — the filters matched nothing. Not an error.
  • After a decision: N decided · N added to the address book · N merged into existing records.
  • Could not load the queue or Decision failed in red, if the server did not answer.

What it writes​

Both buttons call POST /api/address-book/pending-contacts, which calls the decide_bridgemail_pending_contacts database function. That function runs as you — your own permissions decide what may be written, not the sync's.

Reject touches one table:

  • bridgemail_pending_contacts — sets decision to rejected, with your email and the time.

Approve touches two:

  • address_book — for an address already there, fills the blank name, company and vessel and stamps metadata.bridgemail_promoted_at. For an address not there, creates the row with source_purpose set to bridgemail_pending and the sync's guess kept under metadata as provenance. The entity and tenant of an existing record are never changed.
  • bridgemail_pending_contacts — sets decision to approved, same as reject.

Deciding the same rows twice is safe. Only rows still pending are acted on, so a double-submitted batch cannot file the same contact twice — the second attempt reports 0 decided.

The counts can legitimately not add up. If an address exists in the address book but your permissions do not let you see or write that record, it is counted as neither created nor merged, yet the row is still marked approved — because the address demonstrably is in the book already. N decided being larger than created plus merged means exactly that, and is not an error.

When it goes wrong​

The Pending Contacts button is missing from the Address Book. Either the queue is empty or the count did not load. Open /address-book/pending directly to tell the two apart.

"Nothing pending under these filters" when you expect rows. Type is an exact match — check the case. Clear the boxes and press Apply to see the whole queue again.

Approve and Reject stay greyed out. Nothing is ticked. Tick rows, or use Select page.

"Decision failed" or a red error after pressing Approve. Nothing was filed — the batch is refused whole rather than half-applied. Try a smaller selection; if it repeats, report it with the message shown.

You approved something you should not have. It cannot be undone from this screen. Rows the approval created carry source_purpose of bridgemail_pending and a promotion timestamp, so an administrator can identify and remove a bad batch. Rows it merged into only had blanks filled, so nothing anyone had entered was lost.

The same address keeps coming back after you reject it. It should not — rejected rows leave the queue. If it does, the sync is re-queuing it under a second entity; report it rather than rejecting it repeatedly.