Setting Up Mailgun

The aACE+ Mailgun integration allows you to send and receive emails from within your aACE system. Mailgun is 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 instead there is 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 aACE, users initiate an email to be sent by the system (via the Email Viewer, Notices, or using “send email” actions in the Orders, Invoices, and Purchase Orders modules). Rather than opening an email client, aACE creates a record in the Mailgun database and indicates that it is 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:

1. Sign Up for Mailgun
2. Create a Sub-Domain
3. Add the Sub-Domain to Mailgun
4. Add DNS Records to Verify the Sub-Domain
5. Create a Route
6. Input Credentials into aACE
7. Run a Test
8. Verify your Email Results

Step 1: Sign Up for Mailgun

To sign up for Mailgun, visit their Get Started page. Mailgun's "Foundation 50k" plan includes all the needed functionality for integration with aACE.

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

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 originate 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 three days of emails. This means that 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:

1. In aACE, navigate from Main Menu > System Admin > Preferences > Database Management.
2. In the Integrations section, mark the flag for Email Integration. 
3. Next to Email Integration, click the link to Open Settings. 
4. In the Email Integration Settings left-hand panel, click Mailgun.
5. Make sure the flag to Enable Mailgun is marked.
6. 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?
7. Click Test to verify the credentials are entered correctly.
8. Close the test confirmation message, and in the left-hand panel, click General Settings.
9. Enter the following settings to fully enable the aACE integration:
   • Mark the flag to Enable Incoming Email.
   • 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). 
10. 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.
11. 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 will be 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 will 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.

Email processing may take several minutes to complete. 

Step 8: Verify your Email Results

Confirm that:

• The emails do not bounce back in your email client with an error message.
• When you log in to Mailgun and navigate to Logs, both a “Routed” log and a “Stored” log are present, each showing the subject lines of your test emails.
• When you log in to aACE and navigate from Main Menu > CRM & Sales > Emails, your test emails are displayed 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. If a test email still does not show up as expected, contact your aACE partner for assistance.

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 could be done using Mailgun.