Goal: To setup a ticketing system on Zendesk. that uses an email address from my own domain registered with Amazon AWS.
Moving Parts: Emails are sent to an address at my own domain (e.g. firstname.lastname@example.org), controlled by Amazon SES (Simple Email Service). Rules at SES forward all emails to Zendesk, which in turns opens support tickets or sends auto-replies. Anything sent from Zendesk back to senders also shows as having come from my own domain.
- SES needs proof of domain ownership (especially if not hosted with Route 53)
- SES also needs proof of Zendesk email address ownership
- A rule set in SES specifying what to do with incoming emails
- An Amazon Lambda function that will forward emails to Zendesk
- An SPF record to allow Zendesk to send emails on behalf of my domain
1. Verifying A Domain
Amazon SES requires a domain to be verified to confirm that you own it. Otherwise, SES will not allow sending or receiving using custom email addresses, to avoid impersonation. Verification is done by updating DNS settings with a TXT record provided by SES. Use Route 53 if a domain is registered with Amazon. Otherwise use your respective registrar’s DNS editing settings.
3. Click Use Route 53 at the bottom if the domain is registered with Amazon. Otherwise, copy the TXT, CNAME and MX details and enter them into your respective registrar’s DNS section.
4. Click Create Record Sets button. This will automatically update the Route 53 DNS settings if the domain is registered with Amazon. The initial status will say pending verification and should change to say verified within 5 minutes. Domains registered with other providers may take up to 72 hrs to become verified.
2. Zendesk Setup
1. Register with Zendesk. This will give you a basic Zendesk support email address. Emails going through Amazon SES will be forwarded here. But first we need to prove to Amazon SES that we own this email address.
2. In Amazon SES, click on Email Addresses then click Verify a New Email Address and enter the Zendesk email address. You’ll receive an email at Zendesk (that will probably create a ticket) with a verification link. Once clicked, Amazon SES will show this email as verified.
3. Amazon SES Email Receiving Rule Set
At the time of this writing, Amazon SES does not have a native email forwarding feature. One solution is to have emails coming into SES be stored in an Amazon S3 bucket. These emails will then be read by an Amazon Lambda function and forwarded to Zendesk. This order of events is defined by an SES Rule Set.
1. In Amazon SES click on Rule Sets -> View Active Rule Set -> Create Rule and specify the recipient email (e.g. email@example.com).
2. Create an Action of type S3. Then choose to create a new S3 bucket from the dropdown (e.g. maksimkneller-emails) and an Object key prefix (e.g. emails). Click next and give this rule some name and make sure it’s Enabled.
3. Click through until the rule is created. Confirm that it’s enabled, contains a recipient and specifies writing to an S3 bucket. We’ll return to this rule after creating the Lambda function.
4. Create an Amazon Lambda Function
This function will be called by the SES Rule created in the previous step (we’ll append the rule in the next steps). The code in the lambda function will fetch the email from the S3 bucket and execute Node.js forwarding code.
1. Go to the Amazon Lambda service -> Create Function button -> Author From Scratch option. Name the Lambda function, keep Node.js as the runtime. From the Role dropdown select “Create new role from templates” and name it. Choose the “Basic Edge Lambda Permissions” policy template.
2. Once created, a code editor will open with the basic index.js file. The code in this file needs to be replaced by one that performs S3 fetching and forwarding.
3. A popular repository for this action is: https://github.com/arithmetric/aws-lambda-ses-forwarder. The only item needed is the code from the index.js file. Copy and paste it into the lambda code editor.
4. Edit the defaultConfig() section of the code to specify a few email addresses and the S3 bucket. The fromEmail parameter specifies who SES will send the emails as. The forwardMapping section specifies incoming addresses and where the emails should then be forwarded to.
5. Once configured, go back to the SES Rule from the previous step and append a new Action that calls this lambda function.
6. In case SES isn’t able to access the lambda function and gives an error, simply click to Add Permissions.
7. For the lambda function itself to access the S3 bucket and send emails through SES it needs to have permissions to do so. These permissions are defined in the IAM role that was created in the previous lambda step. Go to Amazon IAM service -> select the lambda role -> click the policy name -> click Edit Policy button.
8. Click Add Additional Permissions and add an S3 service with GetObject and PutObject actions. Specify the S3 bucket as a Resource.
9. Add a second service for SES with SendRawEmail action and for all resources.
5. Adding an SPF Record
So far we’ve setup a process for emails coming into our domain to be forwarded to Zendesk. However, for Zendesk to send emails back through our domain, it needs to have permission to do so. An SPF record is a single line of text that declares which SMTP servers, other than your own, are allowed to send email as if it originated from your domain.
1. Add Zendesk’s SPF info as a TXT record into the domain DNS.
1 v=spf1 include:mail.zendesk.com ?all
2. In Zendesk’s advanced email settings, add a new support address and set it to be default. A verification email will be sent that will now pass through Amazon SES back to Zendesk with a confirmation link.
This completes the setup process. Email flow is now completely transparent from a user’s point of view. Zendesk will no longer show up in any of the From or Reply-To fields.