Setting Up Mailgun

This guide explains how to set up and configure your aACE+ Mailgun integration. It is intended for system administrators.

The aACE+ Mailgun integration allows you to send and receive emails from within your aACE system. Mailgun is a product from Rackspace, a leader in transactional email. It is the recommended email product due to its ease of setup, enhanced error capturing, and reliability.

As a transactional email program, Mailgun is designed for email-based solutions that may not involve a person. Think of Mailgun as an email “handler” — there isn’t an inbox, but rather a database of records that are processed from emails (incoming) or processed into emails (outgoing). aACE periodically queries this database for new records that have been created, then downloads them as incoming emails.

Within the system, users initiate an email to be sent by the system (via the Email Viewer, Notices, or using “send email” actions in Orders, Invoices, and Purchase Orders). Rather than opening the mail client, aACE creates a record in the Mailgun database and indicates for it to be sent as an email. This enables emails to be sent from an email account other than the specific individual preparing the message.

Setting up your aACE+ Mailgun integration includes eight steps:

Step 1: Sign Up for Mailgun

Mailgun's "Foundation 50k" plan includes all the needed functionality.

By signing up for your own account (rather than using a common account managed by aACE Software), your email communications will be siloed and inaccessible to anyone outside your organization, including aACE Software.

During the setup, if you are prompted to select a method for integration (i.e. for sending emails), select API with the language set as PHP. Do not select SMTP.

Step 2: Create a Sub-Domain

Create a sub-domain under your company's primary domain (e.g. mg.mycompany.com). If needed, consult with your IT administrator to accomplish this.

Your sub-domain will be used for aACE-related incoming and outgoing emails. Your primary domain should not be used because it may interfere with your organization’s normal incoming and outgoing emails. Neither aACE nor Mailgun will need access to your email server, so your primary domain can remain unchanged.

For additional information on selecting a domain, please consult this Mailgun help guide: How do I pick a domain name for my Mailgun account?

Note: If technical limitations make it impossible to create a sub-domain, another option is to create a separate domain (e.g. www.mycompany.org). This method would allow you to receive incoming emails into aACE, but not reliably send outgoing emails — the messages would be originating from an unrecognized domain and would likely be flagged as spam.

Step 3: Add the Sub-Domain to Mailgun

Log into Mailgun and add your new sub-domain to your account. For additional information, please consult this Mailgun help guide: How do I add a domain?

Step 4: Add DNS Records to Verify the Sub-Domain

TXT and MX records need to be added to your new sub-domain. Please consult with your IT administrator to accomplish this.

For additional information on verifying your domain, please consult this Mailgun help guide: How do I verify my domain?

Note: The Mailgun control panel indicates that MX records may be optional, depending on your implementation. To fully utilize the aACE+ Mailgun integration, both TXT and MX records are required.

Step 5: Create a Route

The route establishes that emails sent to your new domain (e.g. aace@mg.yourcompany.com) will be stored and available to aACE for retrieval. For additional information on setting up a route, please consult this Mailgun help guide: How do I set up a route?

Set up the Mailgun catching route with these settings:

Expression Type: Catch All
Actions: Store and notify
Priority: 0
Description: "Store all incoming emails for retrieval from aACE"

We recommend that you also configure an optional “Forward” route to relay all emails to an external email account that you manage (e.g. aace@yourcompany.com). This email account functions as a backup. Mailgun only stores 3 days of emails; if the automatic process stops temporarily, emails may be lost unless you have a backup.

Set up the Mailgun forwarding route with these settings:

Expression Type: Catch All
Actions: Forward; aace@yourcompany.com
Priority: 1
Description: "Forward all incoming emails to backup email account"

Step 6: Input Credentials into aACE

After you have installed the aACE integration file, proceed with the following steps:

In aACE, navigate from Main Menu > System Admin > Preferences > Database Management.
In the Integrations section, mark the flag for Email Integration.
Next to Email Integration, click the link to Open Settings.
In the Email Integration Settings left-hand panel, click Mailgun.
Make sure the flag to Enable Mailgun is marked.
Enter the setup information from your Mailgun account:
- Domain — Retrieve this by navigating to Mailgun's Domains tab and clicking your sub-domain.
- API Key & Public API Key — Retrieve these by navigating to Mailgun's page for Account Security > API Security. For more details, please consult this Mailgun help guide: Where can I find my API credentials?
Click Test to verify the credentials are entered correctly.
Close the test confirmation message and in the left-hand panel, click General Settings.
Enter the following settings to fully enable the aACE integration:
- Mark the flag to Enable Incoming Email.
- Set the Notice Rec ID for Incoming Email Failure to System Error.
- Mark the flag to Enable Outgoing Email.
- Set the Notice Rec ID for Send Failure to Outgoing Email Error.
- Set the Notice Rec ID for Delivery Failure to Email Not Delivered.
- Enable Test Mode (optional)
  Note: Test Mode will route all outgoing emails to the designated email account(s). If you want multiple people to receive the test emails, you can enter a comma-delimited list of email addresses. This allows you to see how the integration functions without delivering messages to team members not involved with the integration. Marking this flag may impact testing the email functionality (see below).
Close the Email Integration settings window. At the System Preferences module, click Automation Schedules.
1. Mark the flag for the Retrieve Incoming Emails schedule.
2. Mark the flag for the Send Outgoing Emails schedule.
3. Configure the timing for both automation schedules.
Click Commit Updates.

Step 7: Run a Test

Ensure that the email address you are testing with is present in aACE, whether it is your own email address or one specifically designated for Test Mode (see above). The email account can be included on a Contact, Team Member, or Company record. If the sending email address is not found in aACE, the message is treated as junk mail.

Test Incoming Email — In your email client, send a test email to your System Email Address (e.g aace@mg.yourcompany.com). This should prompt the server to create an email record when the automation schedule next runs.
Test Outgoing Email — In aACE, open the Email Viewer from your Contact record and send a test email to an address that you know is present in aACE. This creates an outgoing email record for the server to send.

The email processing may take several minutes. Verify your email results:

The emails do not bounce back in your email client with an error message.
Log into Mailgun and navigate to Logs. Both a “Routed” log and a “Stored” log should be present, each showing the subject lines of your test emails.
Log into aACE and navigate from Main Menu > CRM & Sales > Emails. Your test emails should display there within a few minutes. You may need to use the Quick Search bar to display recent emails.

If a test email does not show up in Mailgun or aACE as expected, one of the first details to verify is that the email addresses are exactly correct.

Do More with Mailgun

The transactional aspect of Mailgun allows for some sophisticated use cases. In our documentation, we summarize email functionality by saying that emails sent to “aACE@mg.yourdomain.com” will download into aACE. This is a simplification. In fact, an email sent to any address on the sub-domain (e.g. newinvoice@mg.yourdomain.com) will download into aACE.

This provides the foundation for a fairly powerful customization: the local-part of the email (i.e. the part before the @ symbol) can be programmed to trigger an event in aACE (e.g. neworder@mg.yourdomain.com or newexpense@mg.yourdomain.com). The local-part can tell aACE what action to perform, while the body of the email can provide the content for that action.

Although we do not recommend automatically sending emails, if you would like to pursue a feature set that includes an emailing component, that would be done using Mailgun.