Setting up Abuse Reports#
Setup takes four steps: prepare a mailbox, enter its details in SynergyCP, give your administrators permission to see reports, and confirm that a test email becomes a report.
Install the Abuse Reports package itself through the Synergy Package Manager as described in Installing Packages. The package adds:
- An Abuse Reports entry in the Network menu of the admin panel (visible to admins with the Read Reports permission) and of the client portal.
- A Server Abuse panel on every server’s page in both portals.
- An Abuse Reports tab under System > Settings.
- Four email templates under System > Emails.
1. Prepare the mailbox#
SynergyCP needs a mailbox of its own that it can log in to over IMAP, read, and move messages around in. Use a dedicated account — SynergyCP will move every message it processes out of the inbox, so do not point it at a personal mailbox.
- Create (or pick) the account and make sure it receives your abuse email. Typically your published abuse contact (
abuse@yourdomain) is either this mailbox or forwards to it. - IMAP must be enabled on the account. SynergyCP always connects with SSL on port 993; plain-text IMAP and other ports are not supported.
- Decide where processed emails should go. SynergyCP moves each processed message from the inbox to an archive folder so it is not imported twice. By default it auto-detects: Gmail and Google Workspace accounts use [Gmail]/All Mail, everything else uses a folder named Archived. On a non-Google server, create the
Archivedfolder (or the folder you intend to configure) before the first sync.
Gmail / Google Workspace: enable IMAP in the account’s Gmail settings. Because Google does not allow the account password for IMAP logins when 2-step verification is on, create an App Password and use that as the IMAP Password below.
Every message in the inbox is treated as an abuse report and moved to the archive folder, including anything already sitting there when you first connect. Clear out or archive old mail you do not want imported before entering the credentials.
2. Enter the package settings#
Go to System > Settings > Abuse Reports:
| Setting | Meaning |
|---|---|
| IMAP Host | Hostname of the IMAP server, e.g. imap.gmail.com. Do not include a port. |
| IMAP User | The mailbox login, which must be an email address, e.g. [email protected]. Emails sent from this address are ignored during sync, so replies you send from the mailbox never become reports. |
| IMAP Password | The mailbox password (or App Password for Google accounts). |
| Archive Folder | IMAP folder processed emails are moved to. Leave empty to auto-detect (Gmail / Google Workspace: [Gmail]/All Mail; other providers: Archived). Use the server’s own folder syntax, e.g. INBOX.Archived on servers that nest folders under INBOX. |
| Sync Frequency (Minutes) | How often the mailbox is checked. Default 5. Values below 1 fall back to 5. |
| Send abuse emails | When ticked, clients are emailed every time a report is assigned to one of their servers, including automatic assignment during sync. Ticked by default. |
| Resolve domain names to IP addresses | Off by default. When ticked, an email that contains no IP address at all has its domain names resolved via DNS, and the report is assigned to the first resolved address that belongs to a server in your deployment. See Domain resolution. |
| Auto Suspension | Days a report may sit unanswered by the client before the server is suspended. Leave empty (or 0) to disable. See Automatic suspension. |
| Maximum Age of Reports | Legacy setting from before version 2.2.0, when the sync filtered the inbox by date. It no longer affects the sync — processed emails are moved to the archive folder instead — and can be left at its default. |
The sync does nothing, and logs “Abuse email sync skipped: IMAP settings are not configured”, until IMAP Host, IMAP User, and IMAP Password are all filled in.
3. Grant permissions#
Abuse Reports are only visible to admins who hold the Abuse Reports > Read Reports permission (pkg.abuse.report.read). Without it the Network > Abuse Reports menu entry and the server page panel are hidden, and API requests are refused. Edit the relevant admin groups under System > Admins and enable the permission.
Clients need no extra permission: each client automatically sees the reports for servers they own or have access to.
4. Review the email templates#
The package installs four templates under System > Emails. Edit them there if you want different wording; the defaults are usable as-is.
| Template | Sent when | Sent to |
|---|---|---|
abuse_report.tpl — “Abuse Report Received” |
A report is assigned to a client’s server (automatically during sync, or by an admin). Requires Send abuse emails. | The client’s abuse contact (see Client abuse contact). Clients who opted out are skipped. |
abuse_report_comment.tpl — “New comment on Abuse Report” |
An admin comments on a report that has a client. | The client’s abuse contact address, even if the client opted out of notifications. |
pkg/abuse/abuse_report_suspend_warning.tpl — “[ABUSE] Upcoming Suspension Warning” |
Daily, while a report is unanswered and auto suspension is enabled. | Every client with access to the server, at their account email. |
pkg/abuse/abuse_report_suspended.tpl — “[ABUSE] Server suspended” |
The server is suspended by auto suspension. | Every client with access to the server, at their account email. |
The report and comment emails include a View Report button that opens the report in the client portal.
5. Verify the setup#
- Send a test email to the mailbox from another address. Put an IP address that is assigned to one of your servers in the subject or body, for example
Abuse report for 203.0.113.10. - Wait for the next sync (up to the Sync Frequency you configured).
- Open Network > Abuse Reports. The report should appear under Waiting on CLIENT if the IP’s server is assigned to a client, or under Unknown if it is not.
- Check the mailbox: the test email should have moved from the inbox to the archive folder.
- If Send abuse emails is on and the server has a client, that client’s abuse contact should have received the “Abuse Report Received” email.
If the report does not appear, open Logs in the admin panel and look for the “Abuse email sync” entries — see Troubleshooting.