Mailbox — Staff Guide

Mailbox — Staff Guide

The Mailbox module brings your email into the CRM. Each staff member connects their own mailbox, syncs incoming mail into a familiar inbox, and works with it in place — reading, replying, organising with folders and rules, and turning individual emails into tasks or leads with one click. This guide covers connecting an account, day-to-day use, and the settings that matter.

1. Where everything lives

The module's left-hand menu holds your folders and tools:

• Inbox — incoming mail that has synced from your account.
• Starred — emails you have flagged with a star.
• Sent — mail you have sent from within the module.
• Important — emails marked important.
• Draft — saved, unsent messages.
• Scheduled — messages queued to send later.
• Trash — deleted emails.
• Archive — emails moved out of the inbox but kept (if enabled).
• Snoozed — emails hidden until a later time (if enabled).
• Email Rules — automatic filing rules for incoming mail.

The Compose email button sits at the top of the menu, and module configuration lives in Settings.

2. Connecting your mailbox

Before any mail appears, your account has to be connected. The module supports two methods:

• OAuth (recommended for Google Workspace / Gmail and Microsoft / Outlook) — you sign in through the provider and grant access; no password is stored in the CRM.
• Password / IMAP — you enter the mail server host, port, encryption, username, and password directly.

To connect with OAuth: open the mailbox configuration, choose your provider (Gmail or Outlook), enter the OAuth Client ID and Client Secret from your provider's cloud console, and save. You will be redirected to the provider to authorise access, then returned to the CRM with the account connected.

Important — OAuth still needs the IMAP server set. Even after a successful OAuth connection, sync uses IMAP under the hood, so the mail server host must be present for mail to pull in. For Google Workspace / Gmail that is imap.gmail.com, port 993, SSL. If your inbox stays empty after connecting, this is the first thing to check with your administrator.

On the provider side (Google Workspace): IMAP access must be enabled for the mailbox (in Gmail: Settings → Forwarding and POP/IMAP → Enable IMAP), and the OAuth grant must include mail access. An account can be fully authorised and still fail to sync if IMAP is switched off at the mailbox level.

3. How mail syncs

Incoming mail is pulled on a schedule by the background cron job — you do not fetch it manually in normal use; new mail simply appears in the Inbox. An administrator can also trigger a manual sync to pull immediately.

Two behaviours are worth knowing:

• Unread-only fetch. By default the module fetches only unread messages from the server. Mail already marked read in your provider before connecting may not import. This keeps load down; it can be changed in Settings (importing everything can be heavy on large mailboxes).
• Nothing is converted automatically. Syncing an email does not create a task or a lead on its own. Those are deliberate, manual actions you take on an email you choose — see section 7.

4. Reading and replying

1. Click an email in the Inbox to open it. You will see the sender, recipients, date, any attachments, and the body.
2. Use Reply, Reply All, or Forward from the open email's action bar.
3. Open Full expands the email into the full detail view, which also carries the Task and Lead actions.

HTML rendering is a per-staff preference: with it on, formatted emails display as intended; with it off, mail is shown as plain text. Set this in your mailbox preferences.

5. Attachments

Emails with attachments show them at the top of the opened message. Click an attachment to download it. Attachments on outgoing mail are added when you compose.

6. Composing and scheduling

1. Click Compose email.
2. Enter recipients, subject, and body; attach files if needed.
3. Send immediately, save as a Draft, or schedule it to go out later — scheduled messages wait in the Scheduled folder and are sent by the cron job.

7. Turning an email into a Task or a Lead

When you open an email, the action bar carries two buttons — Attach to Task and Create Lead. Both are manual: nothing happens to an email until you choose one. They appear on inbox emails (not drafts or sent items).

Attach to Task

Use this to tie an email to your project/task work. A dialog lets you narrow down with a Client → Project → Task cascade:

1. Choose the Client. Projects for that client load automatically.
2. Optionally choose a Project to narrow the task list further.
3. Then either:
   • Link to an existing task — pick a task from the list; the full email is added to it as a comment.
   • Create a new task — give it a name (or leave blank to use the email subject); the task is created, linked to the client/project you chose, and the full email is placed in its description.
4. Click Attach. On success a View task link appears so you can jump straight to it.

The email is copied into the task with a tidy header block (from, to, date, subject) so the task carries the full context.

Create Lead

Use this to bring a new prospect into the CRM from an email. The form pre-fills from the sender — name and email are read from the message, and a company name is inferred from the sender's domain when it is not a generic provider (Gmail, Yahoo, and so on). You then set:

• Source and Status — pick from your CRM's lead sources and statuses.
• Assigned To — defaults to you; change if the lead belongs to a colleague.
• Lead Value and Description — optional; anything you type in Description is kept alongside the original email, which is appended in full.

Click Create Lead; a View lead link appears on success. The action is also recorded in the lead's activity log.

8. Organising your inbox

• Star and Important flags surface emails into their own folders.
• Archive moves an email out of the Inbox without deleting it (if enabled).
• Snooze hides an email until a time you choose, then brings it back (if enabled).
• Trash removes an email to the Trash folder.
• Tags/labels let you categorise mail; multiple tags per email can be enabled in Settings.
• Bulk actions — select several emails and star, archive, mark, or delete them together (when enhanced bulk actions are enabled).

9. Email Rules

Email Rules automatically organise incoming mail. A rule matches on conditions (such as sender or subject) and then takes an action — move to a folder, mark read or important, apply a tag, or send to trash. Rules run as mail arrives during sync.

If synced emails seem to vanish, an active rule is the usual cause — check Email Rules for a rule that moves or trashes matching mail. Rules never create tasks or leads; they only file, flag, or remove.

10. Reminders and the cron job

Scheduled sending and rule processing both depend on the background cron job running. If scheduled mail is not going out or new mail is not appearing, confirm with your administrator that cron is active — most "nothing is happening" symptoms trace back to it.

11. Search

Use the search box for a quick lookup, or Advanced Search (when enabled) to filter by From, Subject, Body, Tags, and Date. Advanced Search is the fastest way to find one email in a busy inbox.

12. Good to know

• OAuth still needs the IMAP server set. A connected Google/Microsoft account will not sync until the mail server host (for Gmail, imap.gmail.com:993/SSL) is present. Empty inbox after connecting? Start here.
• Enable IMAP at the provider. For Google Workspace, IMAP must be switched on for the mailbox or sync fails even with a valid OAuth grant.
• Unread-only by default. Mail already read before connecting may not import unless the fetch setting is changed.
• Nothing auto-converts. Emails become tasks or leads only when you click Attach to Task or Create Lead.
• Task attach uses a Client → Project → Task cascade and can create a new task or link an existing one; the whole email travels with it.
• Create Lead pre-fills from the sender and keeps the original email in the lead's description.
• Missing mail is usually a rule. Check Email Rules before assuming sync is broken.
• Scheduling and rules need cron. If the background schedule is not running, neither fires.