search

devcybiko / ses-catchall

15 stars 8 forks source link

readme

ses-catchall

This is a AWS Lambda that implements SES/Workmail Catchalls.

Workmail has no capability for sending emails to non-registered users to a default inbox. This Lambda-based solution makes it possible.

THEORY

The 'big idea' is to forward any emails that have an "unknown" email address to the selected "default" email address. This is accomplished using SES rules.

A rule is put just before the Workmail rule that creates an SNS message with the incoming email event and sends it to a custom Lambda.

The Lambda determines if the email is one of the already verified user emails. If it is already verified, it passes the event on to Workmail for delivery.

If the recipient is not a verified email, it will update the headers and forward it back to SES as a new email. First, it removes a number of headers (DKIM, etc...) which would interfere with forwarding the email, and sets the recipient to the defaultEmail (specificed in a config object). Also, because SES will not allow unverified senders to deliver email, the TO field is set to the adminEmail (eg: admin@domain.awsapps.com). Finally, this new email is forwarded to SES using the SES.sendRawEmail(). As a convenience, the Reply-To field in the forwarded email is set to the original sender, so that when you click the "Reply" button in the email client, the To field is set appropriately.

The trick here is that the Lambda will screen all incoming emails and look for any sent from the adminEmail. It assumes that anything sent from the adminEmail was previously forwarded and is destined for a defaultEmail inbox. Since the To field was previously reset to the defaultEmail, Workmail dutifully deposits it there.

LIMITATIONS

WARNINGS

async function handler(SNSEvent, context, callback) {
    // return callback(null, { 'disposition': 'STOP_RULE' }); // uncomment this and DEPLOY to curtail an email storm
    let sesMsg = JSON.parse(SNSEvent.Records[0].Sns.Message); log(JSON.stringify(sesMsg, null, 2));
    let originalDestination = sesMsg.mail.destination[0]; log({ originalDestination });

WORKMAIL SETUP

LAMBDA SETUP

  1. In the LAMBDA CONSOLE...
  2. Click: CREATE FUNCTION
  3. "Author From Scratch"
  4. Function Name: ses-default-inbox
  5. Runtime: Node.js 14.x
  6. Architecture: x86_64
  7. Click: CREATE FUNCTION
  8. In the code, replace the index.js with the index.js from the repo
    1. Update the config object with your emails
    2. set defaultEmail to the default email user (eg: greg@agilefrontiers.com)
    3. set adminEmail to the admin user (eg: admin@agilefrontiers.awsapps.com)
    4. set verifiedEmails to the list of users you've already created in Workmail. Email to these users will pass unchanged to Workmail
    5. Optionally add a list of FROM email addresses you'd like filtered out - this is a bit of a spam filter
const config = {
    defaultEmail: "greg@agilefrontiers.com",
    adminEmail: "admin@agilefrontiers.awsapps.com",
    verifiedEmails: [
        "greg@agilefrontiers.com"
    ],
    ignoreEmails: [
        "devcybiko@gmail.com"
    ]
}
  1. In the Configuration -> Permissions, click on the role name
    1. Expand the AWSLambdaBasicExecutionRole...
    2. Click Edit Policy
    3. Click JSON
    4. Add the following policy to the JSON
    5. Click REVIEW POLICY
    6. Click SAVE CHANGES
        {
            "Effect": "Allow",
            "Action": "ses:SendRawEmail",
            "Resource": "*"
        },

SES SETUP

SNS SETUP

{
  "Version": "2008-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "__default_statement_ID",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*",
        "Service": "ses.amazonaws.com"
      },
      "Action": [

TEST IT

  1. Back in the LAMBDA console...
    1. Click the TEST Down-arrow and select CONFIGURE TEST EVENT
    2. replace the JSON with the contents of test.json from the repo
    3. Click SAVE
    4. Click DEPLOY (see the green "Changes Deployed" indicator)
    5. Click TEST and see the results: 
      
Test Event Name
test

Response { "disposition": "CONTINUE" }

Function Logs START RequestId: aec50a9c-8080-4e30-9217-a8a7c5ea8c99 Version: $LATEST 2021-11-20T02:13:00.866Z aec50a9c-8080-4e30-9217-a8a7c5ea8c99 INFO { "mail": { "headers": [ { "name": "From", "value": "test@example.com admin@agilefrontiers.awsapps.com" } ], "destination": [ "test@example.com" ] }, "content": "email content" } 2021-11-20T02:13:00.872Z aec50a9c-8080-4e30-9217-a8a7c5ea8c99 INFO { originalDestination: 'test@example.com' } 2021-11-20T02:13:00.910Z aec50a9c-8080-4e30-9217-a8a7c5ea8c99 INFO { originalLabel: 'test@example.com', originalFrom: 'admin@agilefrontiers.awsapps.com' } 2021-11-20T02:13:00.910Z aec50a9c-8080-4e30-9217-a8a7c5ea8c99 INFO Previously forwarded to default greg@agilefrontiers.com from test@example.com by way of: admin@agilefrontiers.awsapps.com END RequestId: aec50a9c-8080-4e30-9217-a8a7c5ea8c99 REPORT RequestId: aec50a9c-8080-4e30-9217-a8a7c5ea8c99 Duration: 65.32 ms Billed Duration: 66 ms Memory Size: 128 MB Max Memory Used: 74 MB Init Duration: 420.40 ms

Request ID aec50a9c-8080-4e30-9217-a8a7c5ea8c99


## DEBUG / CONSOLE LOG
* You can mute the debugging info by comment out line 26 and uncommenting line 27. 

```js
function dummy() { }
const log = console.log;
// const log = dummy;

FINAL THOUGHTS

Greg Smith