Email channel

Enterprise feature (1.19.0, helpdesk). See the Helpdesk overview.

People can open a request by mailing your help address (help@yourcompany.com), and reply to any helpdesk email to answer on the ticket. CompassDocs doesn’t run a mail server: your mail provider receives the mail and posts each message to the desk’s private webhook address. Replies from the desk go out through your normal SMTP settings.

Turning it on

Desk settings → Email (Email channel capability):

1. Turn on inbound email. This makes the private webhook address your mail provider posts incoming mail to: https://your-domain/api/helpdesk/inbound/<secret>. Copy it.
2. Help address: the address people write to, shown as where to write (help@yourcompany.com). Set it so replies thread by address tag.
3. Sent from (name): the name replies go out under (“IT and HR help desk”), through your CompassDocs mail settings.
4. Who can write in: with Accept mail from outside the workspace off (the default), only people with a CompassDocs account can open tickets by email. Mail from other addresses is ignored and logged, and no reply is sent, so forged senders can’t be used to send mail through you. Trust sender addresses without SPF or DKIM results is here too; leave it off unless your provider reports no results (see Sender authentication).
5. Set up your provider (below) to post to the webhook address, check that it reports sender results, and send yourself a test.

Treat the webhook address like a password: anyone who has it can post mail to the desk. Only people with the Email channel capability see it. Make a new address replaces it; the old address stops working at once, so paste the new one into your provider straight away. The address must be reachable from your provider over HTTPS: if CompassDocs is behind a firewall, allow the provider’s inbound traffic to /api/helpdesk/inbound/.

Add ?provider=postmark, ?provider=sendgrid, ?provider=mailgun or ?provider=generic to the address to say which format your provider sends; the settings page shows the address for each.

What happens to a message

1. Auto-replies, bounces, mailing-list mail and the desk’s own mail are dropped, so two helpdesks never mail each other forever. A message the desk has seen before (a provider’s retry) is dropped as a duplicate.
2. The sender is matched to an account by email address, but only when your mail provider confirms the sender’s domain (see Sender authentication). Unverified mail is treated as mail from outside the workspace.
3. A reply to a ticket is recognised by a private token in the reply address (help+hd-…@), the subject and the Message-ID headers. The requester’s reply, or the reply of an agent who may work the ticket, is added to it with the quoted history cut off. A reply to a closed ticket opens a follow-up ticket instead. Unverified mail is never added to an existing ticket. From 1.19.1, a verified reply from someone copied on the ticket is added too, a reply to a merged ticket lands on the ticket it was merged into, and a customer portal customer’s reply threads into their own ticket even with outside senders off. From 1.19.2, a reply to all without the token joins the ticket too. From 1.19.4, a reply to a ticket in the recycle bin opens a new ticket, as for a closed one, without naming the deleted ticket and without the quoted thread; it never restores it.
4. Anything else is a new ticket, in the team whose alias it was sent to, or the first team. Mail from someone with no account is ignored unless outside senders are allowed; each refusal is logged and audited (helpdesk.inbound.rejected, with the reason). From 1.19.1, when the sender is verified, the people on the Cc line become CCs on the new ticket (the helpdesk’s own addresses and team aliases are left out).
5. Attachments are added to the ticket: images, PDF, text, CSV and Office or OpenDocument files, up to 10 files, 10 MB each and 25 MB in all per message. Any that are not added are listed in a note on the ticket.

The desk keeps the text of every message, never its HTML: an HTML-only message is turned into text. Mail can’t insert images, embeds, videos or disguised links into a ticket: the desk writes every link itself.

Limits: 300 messages a minute for the address, and 20 per sender in 10 minutes. Over the limit the desk answers 429, and providers retry later. A request body over 40 MB is refused, chunked or not.

Replies to all

Sam emails the help address and copies two colleagues. Before the desk has answered, one of them replies to all: “Mine too.” That reply has no token, because no mail from the desk is in the thread yet. Up to 1.19.1 it opened a second ticket. From 1.19.2 it joins Sam’s ticket.

• How it’s matched: the reply’s In-Reply-To and References headers are matched against the Message-IDs of the emails already on the ticket: the one that opened it and any added since, so a reply to someone else’s reply-all threads too.
• Who it works for: only senders who pass sender authentication, and only people already on the ticket: the requester, a CC, an agent who may work it, or the customer portal customer. Anyone else, and any unverified sender, still opens a ticket of their own.
• The same rules as a reply with the token: a reply to a merged ticket lands on the ticket it was merged into, and a reply to a closed ticket opens a follow-up.
• No second copy: the requester and the CCs who were on the reply-all already have it, so the desk’s notice about it reaches them in the bell only, not as another email. CCs who weren’t on it are emailed as usual. The same goes for an agent’s own reply-all.

Nothing new is stored: the desk has kept every incoming Message-ID since 1.19.0.

Team aliases

A team’s email alias (Desk settings → Teams) routes mail: with it@yourcompany.com forwarded to the same webhook and set as IT’s alias, mail to it opens IT tickets. Mail to the main help address goes to the first team, where assignment and automations can move it.

Sender authentication

Anyone can put a colleague’s address in the From line of an email. So the desk links mail to an account only when your mail provider confirms the sender’s domain: DMARC pass, or SPF or DKIM passing for a domain aligned with the From address. The verdict must come from the provider: results the sender wrote into the message’s own headers are ignored.

Without a passing verdict, the mail is treated as coming from outside the workspace:

• with outside senders off (the default), mail from a colleague’s address that can’t be verified is refused, and audited as an unverified sender;
• with outside senders on, it opens a ticket as an outside sender, with a warning on the ticket, and never joins an existing ticket.

A failed check is never trusted. Trust sender addresses without SPF or DKIM results (Desk settings → Email, off by default) links mail that has no results to its account anyway. Turn it on only if your provider reports none: anyone can then send mail that looks like it came from a colleague.

What each provider sends:

Provider	Sender results
SendGrid	Works as set up below: Inbound Parse posts SPF and DKIM results.
Postmark	Works as set up below: Postmark adds Received-SPF and, in X-Spam-Tests, DKIM_VALID_AU.
Mailgun	Turn on spam filtering for the route’s domain, so Mailgun adds X-Mailgun-Spf. SPF that passes for an envelope sender aligned with the From address counts.
Generic JSON	Send spf, dkim and dmarc (each pass, fail and so on; dkim may also be {@domain : pass}), and envelope_from, at the top level or under auth; or pass the provider’s Authentication-Results headers in their original order.

Mail that passes through an internal relay that adds its own Received hops (some Exchange set-ups) can arrive with no verdict the desk can read; it then counts as unverified.

Postmark

1. In Postmark: Servers → your server → Inbound stream → Settings.
2. Paste the webhook address (with ?provider=postmark) as the Webhook URL, and save.
3. Forward help@yourcompany.com to the server’s Postmark inbound address (shown on the same page), or point your domain’s MX record at Postmark.

Refused messages are answered 200, so Postmark doesn’t retry them.

SendGrid

1. In SendGrid: Settings → Inbound Parse → Add Host & URL.
2. Choose the receiving domain (or subdomain), and paste the webhook address (with ?provider=sendgrid) as the Destination URL. Leave POST the raw, full MIME message unticked.
3. Point that domain’s MX record at mx.sendgrid.net.

Mailgun

1. In Mailgun: Receiving → Create route.
2. Expression type: Match recipient, with your help address.
3. Actions: Forward to the webhook address (with ?provider=mailgun). Store and notify works too.
4. Point your domain’s MX records at Mailgun as it shows.
5. Turn on spam filtering for the domain, so Mailgun reports the SPF result (see Sender authentication).

Any other provider (generic JSON)

Any service that can POST JSON can feed the desk. Send Content-Type: application/json to the webhook address (with ?provider=generic):

{
  "from": "Sam Lee <sam@yourcompany.com>",
  "to": "help@yourcompany.com",
  "cc": "",
  "subject": "Laptop won't connect to the VPN",
  "text": "Since this morning ...",
  "html": "<p>Since this morning ...</p>",
  "message_id": "<abc123@mail.yourcompany.com>",
  "in_reply_to": "",
  "references": "",
  "headers": { "Auto-Submitted": "no" },
  "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "envelope_from": "sam@yourcompany.com" },
  "attachments": [
    { "filename": "screenshot.png", "content_type": "image/png", "content": "<base64>" }
  ]
}

from and one of text or html are needed; the rest helps threading and loop protection. Without auth results from your provider, the sender counts as unverified (see Sender authentication).

Mail from monitoring tools

Mail from a monitoring tool is automated, so it is normally dropped. To accept it as alerts, list the tool’s sender address on an email integration. See Integrations.

Replies and templates

Replies, receipts and every other helpdesk email are email templates, with the workspace’s header and footer; a team can have its own version of any helpdesk email (a team signature, for instance) under Desk settings → Email templates. From 1.19.1 a reply goes to the requester with the ticket’s CCs on Cc.

Internal notes by email. When an agent adds an internal note, the assignee gets the Helpdesk: internal note email. It carries no reply address and no thread reference, so it can never become a reply to the requester; if an agent answers it by email anyway, the answer is filed on the ticket as an internal note. From 1.19.4 the Helpdesk: ticket shared with you email works the same way (see Sharing a ticket).

Troubleshooting

Symptom	What to check
Mail never becomes a ticket	Inbound email is off, the provider has an old webhook address, or the sender has no account and outside senders are off (look for helpdesk.inbound.rejected in the audit log).
A colleague’s mail is refused as unverified	Your provider sends no SPF, DKIM or DMARC results, or they failed. See Sender authentication.
Replies open new tickets	The reply lost its token: the requester wrote a fresh email, or a mail gateway rewrote the reply address and the subject. Set the help address so replies carry the tag. A reply to all joins only when its sender is verified and already on the ticket.
The provider reports 404	The webhook address is wrong or was replaced. Copy it again from Desk settings → Email.
The provider reports 402	The helpdesk license is missing or expired.
Attachments are missing	They were over the limits or of a type the desk doesn’t take; the ticket has a note listing them.