Email & Communications Endpoints

Email & Communications

---

Mail

Endpoints for processing inbound mail from various email providers via the HaloIntegrator.

POST /Mail/Azure

Process an Azure/Microsoft 365 email message. No request body schema documented.

POST /Mail/Integrator/Azure

Process an Azure email message via the integrator. No request body schema documented.

POST /Mail/Integrator/Google

Process a Gmail message via the integrator.

Request Body: GmailMessage

POST /Mail/Integrator/Pop3

Process a POP3 email message via the integrator.

Request Body: Pop3Message

Field	Type	Description
id	string	Message identifier
haloMailboxId	integer	ID of the Halo mailbox
incomingEmailId	integer	ID of the incoming email record
mimeMessage	MimeMessage	The raw MIME message object

POST /Mail/Integrator/IMAP

Process an IMAP email message via the integrator.

Request Body: IMAPMessage

Field	Type	Description
id	string	Message identifier
haloMailboxId	integer	ID of the Halo mailbox
incomingEmailId	integer	ID of the incoming email record
mimeMessage	MimeMessage	The raw MIME message object

POST /Mail/ProcessMail

Trigger processing of queued mail items by task ID.

Query Parameters:

Name	Type	Description
task_id	integer	ID of the mail task to process

Request Body: Array of integers (mail item IDs to process)

---

Mailbox

Manage mailbox configurations used for inbound and outbound email in HaloPSA.

GET /Mailbox

List of Mailbox. Returns multiple mailbox records. Requires authentication.

Query Parameters:

Name	Type	Description
department_id	integer	Filter by department
from_addresses	boolean	Include from-address mailboxes
ignore_default	boolean	Ignore the default mailbox
organisation_id	integer	Filter by organisation
showall	boolean	Show all mailboxes including disabled
team_id	integer	Filter by team

POST /Mailbox

Create or update mailbox records.

Request Body: Array of Mailbox objects

Key Mailbox fields:

Field	Type	Description
id	integer	Mailbox ID
name	string	Display name
server	string	Mail server hostname
username	string	Login username
smtpaddress	string	SMTP send address
enabled	boolean	Whether mailbox is active
type	integer	Mailbox type
inbound_method	integer	Inbound polling method
azureemail	string	Azure/M365 email address
azureappid	string	Azure app registration ID
azuretenant	string	Azure tenant ID
google_email	string	Google Workspace email
tickettype_id	integer	Default ticket type for new tickets
restriction_type	integer	Restriction type for inbound matching
restrictto_org_id	integer	Restrict to a specific organisation
restrictto_department_id	integer	Restrict to a specific department
restrictto_team_id	integer	Restrict to a specific team
smtpserver	string	SMTP server hostname
smtpport	integer	SMTP port
smtpusetls	boolean	Use TLS for SMTP
usetls	boolean	Use TLS for inbound
dontsendack	boolean	Suppress acknowledgement emails
ignore_cc_emails	boolean	Ignore CC recipients
accept_auto_replies	boolean	Process auto-reply emails
allow_email_hashtags	boolean	Parse hashtag commands in email
stopnewticketsviaemail	boolean	Block new ticket creation via email
unmatched_users	integer	Action for unmatched sender users
use_emailaddress_for_new_users	boolean	Auto-create users from email address
newuser_default_site	integer	Default site for auto-created users
azure_subscribed	boolean	Whether Azure webhook subscription is active
azure_subscription_expiry	datetime	Expiry date of Azure subscription

GET /Mailbox/{id}

Get one Mailbox. Returns a single mailbox instance. Requires authentication.

Path Parameters: id (integer, required)

Query Parameters:

Name	Type	Description
includedetails	boolean	Include full configuration details
includeglobalsmtp	boolean	Include global SMTP settings

DELETE /Mailbox/{id}

Delete a mailbox by ID.

Path Parameters: id (integer, required)

GET /Mailbox/{id}/OutlookContacts

Retrieve Outlook contacts associated with a mailbox.

Path Parameters: id (integer, required)

---

MailboxCredential

Manage credential records associated with mailboxes.

GET /MailboxCredential

List all mailbox credentials.

POST /MailboxCredential

Create or update mailbox credential records.

Request Body: Array of MailboxCredential objects

GET /MailboxCredential/{id}

Get a single mailbox credential by ID.

Path Parameters: id (integer, required)

DELETE /MailboxCredential/{id}

Delete a mailbox credential by ID.

Path Parameters: id (integer, required)

---

EmailRule

Configure rules for processing inbound emails — match conditions and field extraction.

GET /EmailRule

List of EmailRule. Returns multiple email rule records. Requires authentication.

Query Parameters:

Name	Type	Description
fromaddress	string	Filter rules by from-address pattern
type	integer	Filter by rule type

POST /EmailRule

Create or update email rule records.

Request Body: Array of EmailRule objects

Key EmailRule fields:

Field	Type	Description
id	integer	Rule ID
name	string	Rule name
type	integer	Rule type
pop3serverid	integer	Associated mailbox ID
subject	string	Subject match pattern
body	string	Body match pattern
fromaddr	string	From-address match pattern
toaddr	string	To-address match pattern
fromaddrexact	boolean	Require exact from-address match
toaddrexact	boolean	Require exact to-address match
enabled	boolean	Whether the rule is active
requesttype	integer	Ticket type to create
closestring	string	String that triggers ticket close
dontsendacknowledgement	boolean	Suppress acknowledgement for matched emails
scan_full_body	boolean	Scan entire email body for matches
privateactions	boolean	Create private actions from matched emails
matchonattachment	boolean	Match based on attachment name
attachmentname	string	Attachment filename pattern to match
pagerduty	boolean	Route to PagerDuty
splunkoncall	boolean	Route to Splunk On-Call
always_close_alerts	boolean	Always close matching alert tickets
fieldmappings	array	Field extraction mappings (EmailRuleFieldMapping)

GET /EmailRule/{id}

Get one EmailRule. Returns a single email rule instance. Requires authentication.

Path Parameters: id (integer, required)

Query Parameters:

Name	Type	Description
includedetails	boolean	Include full rule details and mappings

DELETE /EmailRule/{id}

Delete an email rule by ID.

Path Parameters: id (integer, required)

---

EmailStore

Stored outbound email records — emails queued or sent from HaloPSA.

GET /EmailStore

List all stored email records.

POST /EmailStore

Create or queue email records for sending.

Request Body: Array of EmailStore objects

Key EmailStore fields:

Field	Type	Description
id	integer	Record ID
ref	integer	Associated ticket ID
emailsubject	string	Email subject
emailbody	string	Email body (plain text)
emailbody_html	string	Email body (HTML)
emailto	string	To address(es)
emailcc	string	CC address(es)
emailbcc	string	BCC address(es)
dateemailed	datetime	Date the email was sent
mailbox_id	integer	Sending mailbox ID
org_id	integer	Associated organisation ID
client_id	integer	Associated client ID
site_id	integer	Associated site ID
user_id	integer	Associated user ID
templateid	integer	Email template ID used
replyaddress	string	Reply-to address
reply_direct	boolean	Whether reply-to is set directly
invoice_id	integer	Associated invoice ID
quotation_id	integer	Associated quotation ID
purchaseorder_id	integer	Associated purchase order ID
salesorder_id	integer	Associated sales order ID
bulk_user_id_array	array[integer]	User IDs for bulk send
bulk_ticket_id_array	array[integer]	Ticket IDs for bulk send
is_stand_alone_email	boolean	Whether this is a standalone (non-ticket) email
attachments	array	Attached files (Attachment objects)

GET /EmailStore/{id}

Get one EmailStore record. Requires authentication.

Path Parameters: id (integer, required)

Query Parameters:

Name	Type	Description
includedetails	boolean	Include full email details

DELETE /EmailStore/{id}

Delete an email store record by ID.

Path Parameters: id (integer, required)

---

EmailAddressBook

Query the email address book — returns Users that can be addressed via email.

GET /EmailAddressBook

List of Users from the email address book. Requires authentication.

Query Parameters:

Name	Type	Description
search	string	Filter users by name or email
client_id	integer	Filter by client
organisation_id	integer	Filter by organisation
site_id	integer	Filter by site
department_id	integer	Filter by department
toplevel_id	integer	Filter by top-level grouping
asset_id	integer	Filter by assigned asset
contract_id	integer	Filter by contract
opp_id	integer	Filter by opportunity
supplier_id	integer	Filter by supplier
tickettype_id	integer	Filter by ticket type
role	integer	Filter by user role
includeactive	boolean	Include active users
includeinactive	boolean	Include inactive users
activeinactive	string	Comma-separated active/inactive flags
approvers_only	boolean	Return only approver users
allapprovers	boolean	Include all approvers (OR condition)
exclude_agents	boolean	Exclude agent users
exclude_generaluser	boolean	Exclude general users
includeserviceaccount	boolean	Include service account users
includenonserviceaccount	boolean	Include non-service account users
includebillinginfo	boolean	Include billing information
includenotes	boolean	Include user notes
include_custom_fields	string	Comma-separated custom field IDs to include
idonly	boolean	Return only user IDs
search_phonenumbers	boolean	Search phone numbers
integration_type	string	Filter by integration type (okta, azure)
linked_to_user_id	integer	Filter users linked to a specific user
myarea	boolean	Users in your area only
mydepartment	boolean	Users in your department only
mysite	boolean	Users at your site only
mysitecontact	boolean	Your site contacts only
mytoplevel	boolean	Users at your top level only
myallcustomers	boolean	All your customer users
listagentuserfirst	boolean	Order agent-users first
order	string	Primary sort field
order2–order5	string	Secondary sort fields
orderdesc–orderdesc5	boolean	Sort descending for each order field
pageinate	boolean	Enable pagination
page_no	integer	Page number (when paginating)
page_size	integer	Page size (when paginating)
count	integer	Number of results to return (without pagination)
lastupdatefromdate	boolean	Include lastupdatefromdate field
lastupdatetodate	boolean	Include lastupdatetodate field
is_followers	boolean	Filter by followers
is3cxcall	boolean	Filter for 3CX call recipients

---

FormattedEmail

Email templates and formatted outbound message definitions.

GET /formattedemail

List all formatted email records.

POST /formattedemail

Create or update formatted email records.

Request Body: Array of FormattedEmail objects

GET /formattedemail/{id}

Get one formatted email record. Requires authentication.

Path Parameters: id (integer, required)

Query Parameters:

Name	Type	Description
includedetails	boolean	Include full template details

DELETE /formattedemail/{id}

Delete a formatted email record by ID.

Path Parameters: id (integer, required)

---

IncomingEmail

Inbound email queue — emails received by HaloPSA mailboxes awaiting or having been processed into tickets.

GET /incomingemail

List of IncomingEmail. Returns multiple incoming email records. Requires authentication.

Query Parameters:

Name	Type	Description
showcurrentagentonly	boolean	Show only emails assigned to current agent
order–order5	string	Sort fields (1–5)
orderdesc–orderdesc5	boolean	Sort descending for each order field
pageinate	boolean	Enable pagination
page_no	integer	Page number
page_size	integer	Page size