Support

Documentation

Receiving emails

Akeeba Ticket System is primarily designed as a helpdesk component where submitting new tickets and replying to tickets takes place on the site itself. This allows for intricate, time–saving features like the ones described in the earlier sections about custom fields and InstantSearch.

There are, however, many sites where the ticket workflow is best suited to be managed via email, e.g. there are very few categories (possibly even just one), there is only a small number of people managing tickets (possibly even just one), there are no custom fields, clients are expected to prefer sending an email over logging into the site and so on and so forth. Akeeba Ticket System makes it possible to cater for any combination of the following email–to–ticket workflows:

  • Support staff can reply to existing tickets by email.

  • Clients can reply to their existing tickets by email.

  • Clients can submit new tickets by email.

  • Guest users can submit new tickets by email.

These workflows are implemented through the Akeeba Ticket System - Fetch Email plugin and CRON jobs.

Caveats

Email messages are far more limited than full blown websites. The entirety of the information you are receiving over an email message can be summed up like this: name and email address of the sender; subject; email body; attachments.

As a result the following features cannot possibly work over email:

  • Ticket custom fields, Ticket tags, User Tags, Time Spent. There is no reliable way of parsing free text into the structured format of these fields.

  • User information, avatar, total time spent, user groups, previous tickets shown next to each user's reply in a ticket thread. Obviously, these are features which can only be implemented on your site. While some of that information COULD be sent via email it becomes problematic when it comes to attachments, as will be discussed below.

  • InstantSearch. InstantSearch is designed to make search queries and display their results before the client submits their ticket. By definition, once we receive an email the client has already submitted their ticket. Therefore it makes no sense providing them with a link to search results.

  • Canned replies. These are snippets of text which can be inserted in your ticket reply as a Support Staff member. By definition, if you are using an email client application or a webmail site to send replies via email you do not have access to them.

  • Signatures. These are only displayed on the site, they are not included in the email message.

Moreover, receiving new tickets and/or ticket replies over email requires making sense of the subject and body of the email.

The subject is pretty straightforward... unless it contains any character which cannot be encoded in 7-bit ANSI. You see, the original email specification (RFC 822) was written back in 1982 and is in fact a standardization of the hodgepodge of message exchange protocols which sprang in the 1970s, back at the dawn of networked computers. Computers were not capable of displaying characters with diacritics beyond some very basic ones, let alone characters from different character sets like Cyrillic, Greek etc. There is a way to encode full Unicode characters in a way that is sent by email and most email clients support it. ATS will try to parse the subject using those standards and do its best to represent it as real Unicode information which can be stored in your site's database.

The body text is even more complicated. You see, email was designed to send short, plain text messages. Most of the email you see today is actually HTML email, i.e. an HTML document sent as an inline attachment, with or without an alternative, text–only representation. ATS will try its best to divine if the email is plain-text only (very popular among Linux and German users in particular), HTML–only or HTML–with–plain-text. If it's just plain text, ATS will convert it to a basic HTML representation since all ATS posts to tickets are HTML. This works for messages sent from the vast majority of mail clients but it all depends on whether the mail client uses the standard convention of attaching the subject as the first inline attachment in the message. Yes, there is no standard for that, just a convention.

The other problem is that every single image you include in a mail message, including inline images, is in fact an attachment. ATS will process all attachments as such, even if they are inline. This means that the email sender's user account needs to have the Attachments permission to allow these to be attached to their ticket. Furthermore, images anywhere in the document, even those inlined below the “reply above this line” which indicates the end of the client's reply, will be processed as attachments — even if they are part of their signature. On top of that, for security reasons, ATS will NOT display attachment inline. Any inline attachments in mail messages are shown as broken images or empty text. This may make communication with clients problematic if they are using inline images to communicate something. You will have to figure out which one of their attachments corresponds to each inline image they reference in their ticket.

Finally, you need to set up CRON jobs for ATS to periodically check for email. This may be a bit frustrating in the sense that it is not only an additional administrative burden for you as a site owner but also confusing for the client who were they to visit your site would not see their new ticket or ticket reply appear immediately but only after the CRON job has run. Running the CRON jobs too often could bog down your server, running the CRON jobs too infrequently would make clients wonder if their ticket / reply didn't make it through and possibly resend it.

Generally speaking, receiving tickets or ticket replies by email messages should be avoided when possible. The user experience visiting your site to submit a new ticket or reply to an existing ticket will be far superior to using email.

The plugin options

Displayed in the Joomla! Plugin Manager as Akeeba Ticket System - Fetch Email

This plugin allows your site to retrieve email from a mail server and create new tickets or replies to existing tickets based on your settings. It makes the mailfetch CRON command available.

CRON jobs are required

This plugin only provides the infrastructure required to retrieve emails but does not automate the process, i.e. publishing it is required byt NOT sufficient to retrieve emails.

You will need to create a CRON job, either using the CRON CLI script or the CRON URL. Please note that the System - Akeeba Ticket System reply by email plugin has been removed because it had inherent consistency issues when fetching email.

If you are creating a CRON job use the mailfetch CRON command to retrieve emails.

These are the parameters which allow users to reply or create new tickets by sending emails to your site. Please remember to enable the respective plugin or the CRON job script.

Notes on the technology used

Starting with Akeeba Ticket System 3.2.0 we are no longer using the legacy PHP IMAP extension to retrieve and parse email because it has not been maintained since the late 2000's and is no longer up to the task. Instead, we are using the Horde IMAP library which is written in pure PHP and does not require any PHP extensions. It's also faster and much more reliable. Nothing changes from your perspective.

Unless you are using Gmail / G Suite. Because of changes made by Google to their server we can no longer offer the old I am using GMail option and you can not keep on using Gmail / G Suite accounts over IMAP with regular password authentication either. This is NOT because of the library change explained above but because Google decided to discontinue support for a web standard. The reason we are now using the Horde library is that it's the only way we could support the only authentication method Google supports. It is complicated to set up but does work once set up.

The plugin options

Reply by email

When enabled allows users to reply to their tickets by email.

Only for managers

When enabled the Reply by email feature is only available for managers (support staff)

Create ticket by email

When enabled allows users to create new tickets by emails. Obviously, the user needs to send the email from the email address they used to register on your site.

[Warning]Warning

This is dangerous! A user with an auto-reply may cause an endless amount of tickets being created all the time. We strongly recommend NOT using this option.

Track email UID

When enabled Akeeba Ticket System will track the unique identifier of each email message it has processed to prevent double posting of tickets e.g. when an error occurs after a new ticket is created but before it's marked as read / deleted. This is recommended to be enabled on production sites.

If you change email providers or mailboxes this might cause new email to be dropped if the new email provider / mailbox uses the SAME unique IDs as the old one. In this case you will need to disable this option and enable the Delete after post creations option, documented below.

Text version only

When enabled Akeeba Ticket System will try to retrieve the plain text version of the email and use it as the post content. If the user's mail client only sends an HTML version of the email this could cause empty tickets / replies to be created.

Default category

The category where the new tickets created by the "Create ticket by email" feature will be placed.

Mail server type

Your incoming mail server type (IMAP, POP3 or GMail).

If you are using a GMail / G Suite mail account please refer to the "GMail / G Suite Initial Configuration" section of this documentation.

Mail server host

The hostname or IP address of your mail server

Port

The port of your mail server

Use SSL

If your server uses SSL set this to Yes

Use TLS

If your server uses TLS set both this to either When Available or Always and also set Use SSL to Yes

Validate certificates

If you have enabled Use SSL and Use TLS select this option to have ATS verify the SSL certificates presented by your mail server. If the certificates are self-signed this WILL fail. We recommend using this option only when your mail server is using a commercial SSL certificate.

Username

The username you use to connect to your incoming mail server. Usually this is either your email address or the part of your email address before the @ sign. Please consult your email provider.

Password

The password you use to connect to your incoming mail server.

Mail folder

If you have an IMAP / GMail / G Suite mail server select the folder where the messages are stored. This is usually INBOX (all capital letters)

API Client ID

Only applies if you are using a GMail / G Suite mail account. Please refer to the "GMail / G Suite Initial Configuration" section of this documentation.

API Secret Key

Only applies if you are using a GMail / G Suite mail account. Please refer to the "GMail / G Suite Initial Configuration" section of this documentation.

Authorize GMail

Only applies if you are using a GMail / G Suite mail account. Please refer to the "GMail / G Suite Initial Configuration" section of this documentation.

Access Token

Only applies if you are using a GMail / G Suite mail account. Please refer to the "GMail / G Suite Initial Configuration" section of this documentation.

Refresh Token

Only applies if you are using a GMail / G Suite mail account. Please refer to the "GMail / G Suite Initial Configuration" section of this documentation.

Delete after post creations

Should the retrieved email messages be deleted from the server after the post/ticket has been created? If this is set to No then the emails are only marked as read. If you set this option to No we strongly advise that you set Track email UID to Yes.