README.yaml

name: terraform-aws-ses-lambda-forwarder
license: APACHE2
github_repo: cloudposse/terraform-aws-ses-lambda-forwarder
badges:
- name: Latest Release
  image: https://img.shields.io/github/release/cloudposse/terraform-aws-ses-lambda-forwarder.svg
  url: https://github.com/cloudposse/terraform-aws-ses-lambda-forwarder/releases/latest
- name: Slack Community
  image: https://slack.cloudposse.com/badge.svg
  url: https://slack.cloudposse.com
description: This is a terraform module that creates an email forwarder using a combination
  of AWS SES and Lambda running the [aws-lambda-ses-forwarder](https://www.npmjs.com/package/aws-lambda-ses-forwarder)
  NPM module.
introduction: |-
  This module provisions a NodeJS script as a AWS Lambda function that uses the inbound/outbound capabilities of AWS Simple Email Service (SES) to run a "serverless" email forwarding service.

  Use this module instead of setting up an email server on a dedicated EC2 instance to handle email redirects. It uses AWS SES to receive email and then trigger a Lambda function to process it and forward it on to the chosen destination.  This script will allow forwarding emails from any sender to verified destination emails (e.g. opt-in).

  ## Limitations

  The SES service only allows sending email from verified addresses or domains. As such, it's mostly suitable for transactional emails (e.g. alerts or notifications). The incoming messages are modified to allow forwarding through SES and reflect the original sender. This script adds a `Reply-To` header with the original sender's email address, but the `From` header is changed to display the SES email address.

  For example, an email sent by `John Doe <jonh@example.com>` to `hello@example.com` will be transformed to:
  ```
  From: John Doe at john@example.com <hello@example.com>
  Reply-To: john@example.com
  ```

  To override this behavior, set a verified `fromEmail` address (e.g., `noreply@example.com`) in the config
  object and the header will look like this.
  ```
  From: John Doe <noreply@example.com>
  Reply-To: john@example.com
  ```

  __NOTE__: SES only allows receiving email sent to addresses within verified domains. For more information,
  see: http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html
  ```

  Initially SES users are in a sandbox environment that has a number of limitations. See:
  http://docs.aws.amazon.com/ses/latest/DeveloperGuide/limits.html
usage: |2-

  For a complete example, see [examples/complete](examples/complete).

  For automated tests of the complete example using [bats](https://github.com/bats-core/bats-core) and [Terratest](https://github.com/gruntwork-io/terratest) (which tests and deploys the example on AWS), see [test](test).

  ```hcl
  variable "relay_email" {
    default     = "example@example.com"
    description = "Email that used to relay from"
  }

  variable "forward_emails" {
    type = map(list(string))

    default = {
      "some_email@example.com"  = ["my_email@example.com"]
      "other_email@example.com" = ["my_email@example.com"]
    }

    description = "Emails forward map"
  }

  module "ses_lambda_forwarder" {
    source = "cloudposse/ses-lambda-forwarder/aws"
    # Cloud Posse recommends pinning every module to a specific version
    # version = "x.x.x"

    namespace  = var.namespace
    stage      = var.stage
    name       = var.name
    delimiter  = var.delimiter
    attributes = var.attributes
    tags       = var.tags

    region = var.region
    domain = var.domain

    relay_email    = var.relay_email
    forward_emails = var.forward_emails
  }
  ```
references:
- name: aws-lambda-ses-forwarder
  description: A Node.js script for AWS Lambda that uses the inbound/outbound capabilities
    of AWS Simple Email Service (SES) to run a "serverless" email forwarding service.
  url: https://www.npmjs.com/package/aws-lambda-ses-forwarder
include:
- docs/targets.md
- docs/terraform.md
contributors:
- name: Igor Rodionov
  github: goruha
- name: Erik Osterman
  github: osterman
- name: Andriy Knysh
  github: aknysh