{"id":21213991,"url":"https://github.com/cruxstack/terraform-aws-cognito-custom-message-sender","last_synced_at":"2026-01-17T23:33:21.443Z","repository":{"id":179990525,"uuid":"664080728","full_name":"cruxstack/terraform-aws-cognito-custom-message-sender","owner":"cruxstack","description":"Terraform Module to deploy customizable Cognito custom message sender serivce for SMS and email","archived":false,"fork":false,"pushed_at":"2026-01-12T18:57:03.000Z","size":218,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T00:12:32.870Z","etag":null,"topics":["aws","aws-cognito","aws-lambda","cloudposse","email","serverless","sms","sweetops","terraform","terraform-module","trigger","triggers"],"latest_commit_sha":null,"homepage":"https://registry.terraform.io/modules/cruxstack/cognito-custom-message-sender/aws/latest","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cruxstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-08T21:28:40.000Z","updated_at":"2026-01-12T18:56:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"853bd638-4b08-4e31-8896-4fae1f1aad78","html_url":"https://github.com/cruxstack/terraform-aws-cognito-custom-message-sender","commit_stats":null,"previous_names":["sgtoj/terraform-aws-cognito-custom-message-sender","cruxstack/terraform-aws-cognito-custom-message-sender"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/cruxstack/terraform-aws-cognito-custom-message-sender","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cruxstack%2Fterraform-aws-cognito-custom-message-sender","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cruxstack%2Fterraform-aws-cognito-custom-message-sender/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cruxstack%2Fterraform-aws-cognito-custom-message-sender/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cruxstack%2Fterraform-aws-cognito-custom-message-sender/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cruxstack","download_url":"https://codeload.github.com/cruxstack/terraform-aws-cognito-custom-message-sender/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cruxstack%2Fterraform-aws-cognito-custom-message-sender/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28522309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cognito","aws-lambda","cloudposse","email","serverless","sms","sweetops","terraform","terraform-module","trigger","triggers"],"created_at":"2024-11-20T21:25:26.519Z","updated_at":"2026-01-17T23:33:21.434Z","avatar_url":"https://github.com/cruxstack.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terraform Module: AWS Cognito Custom Message Sender\n\nThis Terraform module deploys AWS Lambda functions to serve as custom SMS and\nemail senders for AWS Cognito. The module uses Open Policy Agent (OPA) policies\nto determine whether to send messages, and can be customized to fit various use\ncases, such as throttling messages, routing emails by client ID, or preventing\nmessages from being sent to specific destinations.\n\nFor more details about the custom message sender Lambda function, see [documentation](./assets/custom-message-sender/)\nlocated within its directory.\n\n## Features\n\n- [Custom SMS sender Lambda function for AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-sms-sender.html)\n  - Customizable (OPA) policy to filter and throttle SMS sending\n  - Ability to dynamically use SMS sender ID and short code\n- [Custom Email sender Lambda function for AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-email-sender.html)\n  - Dynamic template selection based on context (client ID, trigger type, etc.)\n  - Multiple email providers: AWS SES or SendGrid\n  - Automatic provider failover (SES to SendGrid) when primary provider is unavailable\n  - Email verification support (offline RFC 5322 validation or SendGrid API)\n\n## Usage\n\n```hcl\nmodule \"cognito_custom_sms_sender\" {\n  source  = \"cruxstack/cognito-custom-message-sender/aws\"\n  version = \"x.x.x\"\n\n  email_sender_enabled                    = true\n  email_sender_policy_content             = \"\u003cOPA policy content\u003e\"\n\n  sms_sender_enabled                    = true\n  sms_sender_policy_content             = \"\u003cOPA policy content\u003e\"\n  sms_sender_throttle_period_in_minutes = 15\n}\n```\n\n## Inputs\n\nIn addition to the variables documented below, this module includes several\nother optional variables (e.g., `name`, `tags`, etc.) provided by the\n`cloudposse/label/null` module. Please refer to its [documentation](https://registry.terraform.io/modules/cloudposse/label/null/latest)\nfor more details on these variables.\n\n### General\n\n| Name                   | Description                                                                            |   Type   | Default   | Required |\n|------------------------|----------------------------------------------------------------------------------------|:--------:|:---------:|:--------:|\n| `kms_key_alias_prefix` | The prefix for the KMS key alias.                                                      | `string` | `\"alias\"` |    no    |\n| `service_log_level`    | The log level for the service. Must be 'debug', 'info', 'warn', 'error', or 'fatal'.   | `string` | `\"info\"`  |    no    |\n| `aws_account_id`       | The AWS account ID that the module will be deployed in.                                | `string` | `\"\"`      |    no    |\n| `aws_region_name`      | The AWS region name where the module will be deployed.                                 | `string` | `\"\"`      |    no    |\n\n### Email Sender\n\n| Name                            | Description                                                                                                                              |    Type     |   Default   | Required |\n|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|:-----------:|:-----------:|:--------:|\n| `email_sender_enabled`          | Whether or not the email sender is enabled.                                                                                              |   `bool`    |   `false`   |    no    |\n| `email_sender_version`          | Version or git ref of the source code.                                                                                                   |  `string`   |  `\"latest\"` |    no    |\n| `email_sender_policy_content`   | The content of the Open Policy Agent policy for email sender. Must include 'package cognito_custom_sender_email_policy'.                 |  `string`   |     n/a     |   yes    |\n| `email_sender_providers`        | List of enabled email providers.                                                                                                         | `list(str)` |  `[\"ses\"]`  |    no    |\n| `email_verification_enabled`    | Toggle to enable email verification before sending.                                                                                      |   `bool`    |   `true`    |    no    |\n| `email_verification_provider`   | Email verification provider: 'offline' (RFC 5322 format) or 'sendgrid' (advanced checks).                                                |  `string`   | `\"offline\"` |    no    |\n| `email_verification_whitelist`  | List of email domains that skip email verification.                                                                                      | `list(str)` |    `[]`     |    no    |\n| `email_failover_enabled`        | Enable automatic provider failover when primary provider is unavailable.                                                                 |   `bool`    |   `false`   |    no    |\n| `email_failover_providers`      | List of failover providers to try when primary fails (e.g., `[\"sendgrid\"]`).                                                             | `list(str)` |    `[]`     |    no    |\n| `email_failover_cache_ttl`      | Health check cache duration for failover (Go duration format, e.g., '30s').                                                              |  `string`   |   `\"30s\"`   |    no    |\n\n### SendGrid\n\n| Name                                | Description                                                  |   Type   |          Default            | Required |\n|-------------------------------------|--------------------------------------------------------------|:--------:|:---------------------------:|:--------:|\n| `sendgrid_api_host`                 | SendGrid API base URL.                                       | `string` | `\"https://api.sendgrid.com\"`|    no    |\n| `sendgrid_email_send_api_key`       | The SendGrid API key for sending emails.                     | `string` |            `\"\"`             |    no    |\n| `sendgrid_email_verification_api_key` | The SendGrid API key for email verification.               | `string` |            `\"\"`             |    no    |\n\n### SMS Sender\n\n| Name                                    | Description                                                                                                                        |   Type   | Default | Required |\n|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|:--------:|:-------:|:--------:|\n| `sms_sender_enabled`                    | Whether or not the SMS sender is enabled.                                                                                          |  `bool`  | `false` |    no    |\n| `sms_sender_policy_content`             | The content of the Open Policy Agent policy for SMS sender. Must include 'package cognito_custom_sender_sms_policy'.               | `string` |   n/a   |   yes    |\n| `sms_sender_throttle_period_in_minutes` | The throttle period for the SMS sender, in minutes. Must be a positive integer.                                                    | `number` |  `15`   |    no    |\n\n## Outputs\n\n| Name                 | Description                                                             |\n|----------------------|-------------------------------------------------------------------------|\n| `kms_key_arn`        | The ARN of the KMS key.                                                 |\n| `email_lambda_fn_arn`| The ARN of the email sender Lambda function (empty if disabled).        |\n| `sms_lambda_fn_arn`  | The ARN of the SMS sender Lambda function (empty if disabled).          |\n\n## Provider Failover\n\nAWS can suspend SES sending at any time for compliance reasons. Enable automatic\nfailover to ensure emails continue to be delivered via an alternative provider.\n\n```hcl\nmodule \"cognito_custom_message_sender\" {\n  source  = \"cruxstack/cognito-custom-message-sender/aws\"\n\n  email_sender_enabled        = true\n  email_sender_providers      = [\"ses\"]\n  email_sender_policy_content = file(\"policy.rego\")\n\n  # Enable failover with SendGrid as backup\n  email_failover_enabled  = true\n  email_failover_providers = [\"sendgrid\"]\n\n  # SendGrid credentials (required when in failover chain)\n  sendgrid_email_send_api_key = \"SG.xxxx\"\n}\n```\n\nWhen failover is enabled, your OPA policy **must** return template configurations\nfor all providers in the failover chain:\n\n```rego\nresult := {\n  \"action\": \"allow\",\n  \"allow\": {\n    \"srcAddress\": \"noreply@example.com\",\n    \"dstAddress\": input.userAttributes.email,\n    \"providers\": {\n      \"ses\": {\n        \"templateId\": \"ses-verification-template\",\n        \"templateData\": {\"appName\": \"MyApp\"}\n      },\n      \"sendgrid\": {\n        \"templateId\": \"d-abc123def456\",\n        \"templateData\": {\"appName\": \"MyApp\"}\n      }\n    }\n  }\n}\n```\n\n## Migration to v1.x (Breaking Changes)\n\nThe upstream Go application has upgraded to v2.x which requires:\n\n### 1. Rego v1 Syntax\n\nOPA policies must use v1 syntax with `import rego.v1` and explicit `if` keyword:\n\n```rego\n# Before (v0.x)\npackage cognito_custom_sender_email_policy\n\nresult := allow_result {\n  not deny_result\n}\n\n# After (v1.x)\npackage cognito_custom_sender_email_policy\nimport rego.v1\n\nresult := allow_result if {\n  not deny_result\n}\n```\n\n### 2. Environment Variable Changes\n\n| Deprecated Variable                         | New Variable                       |\n|---------------------------------------------|------------------------------------|\n| `sendgrid_email_verification_enabled`       | `email_verification_enabled`       |\n| `sendgrid_email_verification_allowlist`     | `email_verification_whitelist`     |\n\nThe deprecated variables still work for backwards compatibility but will be\nremoved in a future version.\n\n## Contributing\n\nWe welcome contributions to the project! For information on setting up a\ndevelopment environment and how to make contribution, see [CONTRIBUTING](./CONTRIBUTING.md)\ndocumentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcruxstack%2Fterraform-aws-cognito-custom-message-sender","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcruxstack%2Fterraform-aws-cognito-custom-message-sender","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcruxstack%2Fterraform-aws-cognito-custom-message-sender/lists"}