AWS Messaging as API

Module Downloads metrics from Terraform Registry

Data Snapshot as of October 2, 2024

00

Downloads this week

00

Downloads this month

00

Downloads this year

00

Downloads over all time

Effortless REST API for Messaing: Email, SMS and Push Notifications

• Effortless Development: This module allows you to create a fully functional REST API to send Emails and SMS
• Simplify API Creation: Setting up Pinpoint and REST APIs in AWS can be time-consuming and require advanced knowledge. This module eliminates the need for complex configurations, saving you valuable development time.

API endpoints

This module will create Edge-optimized API endpoints in the below format

Base URL

API's base URL will contain the API Name and Domain name, if you provided domain_name or hosted_zone_id . If not provided, then it will return the URL defined by AWS.

# Endpoints with Domain Name
https://<api-name>.<domain.com>/<api-version>

# Endpoints without Domain Name
https://<apigateway-id>.execute-api.<aws-region>.amazonaws.com/prod_<api-version>

Endpoints

All endpoints will follow the format given below

# If you selected to create "email" channel
POST: <base-url>/<project-name>/send-email

Custom Domain

If you are maintaining your domain with AWS, you can provide verify_domain_identity = true. This module will create a Domain identitiy and will be verified by adding DNS records to Route53.

Since the API is edge-optimized, API Gateway internally creates and manages a CloudFront distribution to route requests on the given hostname. This module will create a DNS record corresponding to the given domain name which is an alias in Route53 to the Cloudfront.

Provider alias for Custom Domain

If you dont't want yor Pinpoint projects created in US-East, you should define 2 AWS providers. Provider 1. One with region = "us-east-1" and an alias name (see below example). This is to provision SSL/TLS certificate in US-East region. Provider 2. Default AWS provider with any region you would like to create Pinpoint projects and API. You can define an alias name if you want to specify the purpose (see below example), but alias is optional for default provider.

Below is code sample to declare providers

# provider.tf
# AWS provider for creating SSL/TLS certificate for your website
provider "aws" {
  profile = "profile name configured in %USERPROFILE%\.aws\credentials"
  region  = "us-east-1" # (AWS will create SSL/TLS certificate in US-East-1 region only)
  alias   = "provder_for_ssl"
}

# default AWS provider for creating website and other resources
provider "aws" {
  profile = "profile name configured in %USERPROFILE%\.aws\credentials"  
  region  = "AWS region where DynamoDB tables exists"
  alias   = "provder_for_api" # (alias name for default provider is optional)
}

How to Execute this Module

You can execute this module by providing single/multiple Project names. Below is a sample code.

# main.tf
module "messaging-as-api" {
  source  = "CloudPediaAI/messaging-as-api/aws"
  version = "1.0.2"

  api_name = "marketing"
  api_domain_name = "company"
  projects = {
    "project1" = {
      channels               = ["email"]
      from_email             = "project1@company.com",
      to_emails              = ["test@company.com"],
      need_api_endpoint      = true,
      verify_domain_identity = true
    },
    "project2" = {
      channels               = ["email"]
      from_email             = "non-reply@company.com",
      to_emails              = ["test@company.com"],
      need_api_endpoint      = true,
      verify_domain_identity = false
    }
  }
  need_smtp_user = false
}

Endpoints Example

Above code will create 2 projects in Pinpoint and an API marketing with POST endpoints project1/send-email and project2/send-email. Sample API endpoints are given below.

# Base URL
https://marketing.company.com/v1 

# Assumption: Both projects need email channel and need API endpoints
GET: /project1/send-email
GET: /project2/send-email

Response Format

All GET endpoint responses follow the JSend specification.

Sample Response if email sent successfully

Notice that the response code will be 200

{
  "status" : "success",
  "count": 0,
  "id": "xx",
  "data": null
}

API Version

If custom domain configured, the value assigned to api_version will be mapped to the deployed API Stage and it is going to be part of the URL. If there is no custom domain, api_version will get suffixed to the Stage name (eg. prod_v1).

Follow Semantic Versioning for the API version. eg. v1 or v1.0 or v1.0.0.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

Security Configuration

This module will create to IAM roles:

• IAM role for Lambda to execure Pinpoint functionalities
• IAM role for API Gateway to executre Lambda

API Authentication

• Cognito User Pool for Authentication: You can protect your API by leveraging a Cognito User Pool. Simply assign the ARN of your Cognito User Pool to the cognito_user_pool_arns variable. This will create an Authorizer and attach it to all API methods. Once implemented, users will need to pass a valid ID Token obtained through authentication in the Authorization header to access the API.

Custom Domain and SSL/TLS Encryption

• Custom Domain with SSL/TLS: If you manage your domain within AWS, you can provide value for either the domain_name or the hosted_zone_id variable. This module will automatically create a Custom Domain for your API and include an SSL/TLS certificate issued by AWS with latest TLS version.

Output variables

Below are the Output variables you will get after applying this module

• domain_identities : All domain identities created
• email_identities: All email identifies created
• smtp_user: SMTP user details if you assigned need_smtp_user = true
• smtp_user_access_key: Access key to call SMTP services

Helpful Resources

• Published Module in Terraform Registry
• Source Code Repository in GitHub
• Release Notes

Akbar Hussain

Cloud Architect

An accomplished Cloud Architect with over 20+ years of experience in Application Development, Cloud, DevSecOps and Cybersecurity. Helping clients on their digital transformation, cloud migration, application modernization, cost & process optimization, cybersecurity validations and incident management.