Agendando campanhas de e-mail em escala com o Amazon EventBridge Scheduler

Por Oluwaseun Ademuwagun, Serda Kasaci Yildirim e Rana Kiziltoprak German, Solutions Architects na Amazon Web Services.

O agendamento de campanhas de e-mail se torna mais complexo quando você precisa enviar e-mails para milhões de destinatários no horário único que melhor se adequa a cada cliente. Considere estes exemplos:

Uma promoção relâmpago pode precisar chegar às caixas de entrada às 9h no horário local de cada fuso horário.
Um e-mail de acompanhamento (frequentemente conhecido como sequência de drip) pode precisar enviar uma segunda mensagem exatamente 3 dias após a primeira mensagem por assinante.
Uma campanha de reengajamento pode ter como alvo usuários que não fizeram login por 30 dias.

Os requisitos de agendamento envolvem diversas considerações. Você está enviando centenas de milhões de mensagens, cada uma em seu próprio momento ideal, personalizado de acordo com o fuso horário e o comportamento do destinatário.

Nesta publicação, mostramos como usar o Amazon EventBridge Scheduler para personalizar notificações por e-mail para cada destinatário. Criamos um agendamento por destinatário para entregar cada e-mail em seu momento individualmente ideal, sem nenhum custo de computação ocioso. Também mostramos como o Amazon EventBridge Scheduler lida com volumes maiores. O Amazon EventBridge Scheduler suporta bilhões de agendamentos. Por padrão, você tem uma cota de 10 milhões de agendamentos.

Visão geral da solução

Quando cada destinatário tem seu próprio horário de entrega ideal, você precisa de uma camada de agendamento capaz de manter bilhões de intenções de envio individuais e disparar cada uma no momento certo. A maioria das equipes recorre a um de três padrões familiares, cada um com desvantagens que se tornam dolorosas em escala.

Jobs de lote (batch cron jobs): um job é executado a cada hora, consulta todas as mensagens vencidas na próxima janela e as envia. Os destinatários recebem e-mails em lotes horários imprecisos. Em escala, o próprio job em lote se torna um gargalo, processando milhões de linhas por execução, competindo por conexões de banco de dados e criando um pico repentino de carga no provedor de e-mail.
Filas de atraso (delay queues): você pode usar o Amazon Simple Queue Service (Amazon SQS) como uma fila de atraso. Uma fila de atraso posterga a entrega de novas mensagens a um cliente por um tempo determinado. Uma limitação dessa abordagem é que o Amazon SQS limita os atrasos a 15 minutos.
Ferramentas de campanha de terceiros: transferir para uma plataforma SaaS de e-mail. Isso funciona até que você precise de integração estreita com os dados da sua aplicação, otimização personalizada do horário de envio ou controle sobre a infraestrutura de entrega. Você também paga taxas por destinatário que se acumulam em escala.

As três abordagens ou sacrificam a precisão (processamento em lote), ou atingem limites arquiteturais (filas de atraso), ou abrem mão do controle (ferramentas de terceiros).

A abordagem por blocos de construção

O Amazon EventBridge Scheduler trata cada envio de e-mail como uma ação agendada discreta. Em vez de “processar todas as mensagens vencidas nesta hora”, você expressa a intenção diretamente: “enviar este e-mail para esta pessoa neste horário”. O Amazon EventBridge Scheduler mantém essa intenção com custo de computação zero até o momento chegar e, então, dispara a ação agendada. Consulte o Guia do Usuário do Amazon EventBridge Scheduler para a referência completa da API e as cotas de serviço atuais.

Para campanhas de e-mail, o Amazon EventBridge Scheduler se torna o despachante de horário de envio, o componente que agenda cada e-mail de uma campanha para seu momento individualmente ideal, seja ele ajustado por fuso horário, acionado por comportamento ou orientado por sequência.

Diagrama de arquitetura

A arquitetura segue um padrão de agendamento por destinatário orientado a eventos para uma campanha de e-mail. Para iniciar a campanha, você primeiro define o público-alvo e o conteúdo que ele receberá. A seguir, você precisa de uma forma de criar o agendamento por destinatário. Para fazer isso em uma campanha que pode conter milhões de destinatários, você precisa de um mecanismo escalável para criar os agendamentos. Você pode conseguir isso com uma máquina de estados do AWS Step Functions, um serviço de workflow sem servidor que coordena diversos serviços da AWS em fluxos de trabalho estruturados e visuais chamados máquinas de estados. Nesta solução, orquestramos a criação dos agendamentos usando um estado Distributed Map dentro da máquina de estados, que nos permite distribuir e acelerar a criação de agendamentos. Isso é feito dividindo um grande conjunto de dados em partes e processando-as em milhares de execuções filhas paralelas. Ele lê a lista de destinatários do Amazon Simple Storage Service (Amazon S3), aplica a lógica de fuso horário por destinatário e cria um recurso individual do Amazon EventBridge Scheduler para cada destinatário em paralelo. Depois que o workflow cria todos os agendamentos, a execução é concluída.

A entrega real do e-mail ocorre posteriormente, totalmente desacoplada da etapa de criação da campanha. No horário agendado, o Amazon EventBridge Scheduler invoca diretamente o Amazon Simple Email Service (Amazon SES), passando o nome do template e os dados de personalização como variáveis de template. Para campanhas que exigem lógica de personalização complexa (conteúdo condicional, verificações de supressão em tempo real ou enriquecimento de dados), você pode, opcionalmente, encaminhar por meio de uma função do AWS Lambda antes do SES. Se você precisar ajustar o horário ou o conteúdo para destinatários específicos, pode atualizar seus agendamentos individuais diretamente, sem reprocessar toda a campanha.

Figura 1: Arquitetura de agendamento de e-mail por destinatário com o Amazon EventBridge Scheduler

Passo a passo

A solução usa quatro componentes principais que trabalham em conjunto: um gerenciador de campanha para definir regras de horário de envio, o Distributed Map do Step Functions para distribuir e acelerar a criação de agendamentos, o Amazon EventBridge Scheduler para manter a intenção de cada destinatário e entregar diretamente por meio do Amazon SES, e limpeza automática por meio da autoexclusão do agendamento.

Como funciona

Criar a campanha: um profissional de marketing define a campanha: segmento de público, template de e-mail e regras de horário de envio (por exemplo, “9h no fuso horário local de cada destinatário” ou “24 horas antes de uma promoção de Black Friday”).
O gerenciador de campanha distribui a carga: um workflow do AWS Step Functions usa o Distributed Map para iterar sobre a lista de destinatários e criar um agendamento do Amazon EventBridge Scheduler por destinatário para cada etapa da campanha, diretamente por meio de integração com o SDK. Cada agendamento codifica o horário exato de envio para aquele indivíduo.
O Amazon EventBridge Scheduler dispara no momento certo: no horário agendado de cada destinatário, o Amazon EventBridge Scheduler invoca o Amazon SES diretamente por meio de um alvo universal (universal target), passando o nome do template e os dados de personalização (nome do destinatário e atributos) como variáveis de template.
O SES personaliza e envia: o Amazon SES renderiza o template de e-mail com os dados fornecidos e entrega a mensagem.
O agendamento se autoexclui: ActionAfterCompletion='DELETE' evita o acúmulo de agendamentos já utilizados.

Pré-requisitos

Para acompanhar este passo a passo, você precisa do seguinte:

Conta da AWS e permissões: uma conta da AWS ativa com permissões para criar agendamentos do Amazon EventBridge Scheduler, máquinas de estados do AWS Step Functions e identidades do Amazon SES, além de uma função do AWS Identity and Access Management (IAM) para que o Amazon EventBridge Scheduler possa invocar o Amazon SES.
Ambiente de desenvolvimento: Python 3.13 ou posterior, AWS SDK for Python (Boto3) versão 1.26 ou posterior e AWS Command Line Interface v2 (AWS CLI v2).
Configuração do Amazon SES: mova sua conta do Amazon SES para fora do modo sandbox para permitir o envio para destinatários arbitrários.

Escalando a distribuição com o Step Functions

Para campanhas com milhões de destinatários, use o Distributed Map do AWS Step Functions para paralelizar a criação de agendamentos. Quando você deseja ativar uma campanha, aciona um workflow do Step Functions. Esse workflow distribui a carga e cria agendamentos em toda a lista de destinatários usando um Distributed Map com integração direta ao SDK. A integração direta ao SDK entre o Step Functions e o Amazon EventBridge Scheduler permite que cada execução filha chame CreateSchedule diretamente. A definição de máquina de estados a seguir lê os destinatários de um arquivo CSV no Amazon S3 e cria agendamentos em paralelo:

{
  "Comment": "Fan out campaign schedule creation via direct SDK integration",
  "StartAt": "EnsureScheduleGroup",
  "States": {
    "EnsureScheduleGroup": {
      "Type": "Task",
      "Resource": "arn:aws:states:::aws-sdk:scheduler:createScheduleGroup",
      "Parameters": {
        "Name.$": "States.Format('campaign-{}', $.campaign_id)"
      },
      "ResultPath": null,
      "Catch": [
        {
          "ErrorEquals": [
            "Scheduler.ConflictException"
          ],
          "ResultPath": null,
          "Next": "FanOutRecipients"
        }
      ],
      "Next": "FanOutRecipients"
    },
    "FanOutRecipients": {
      "Type": "Map",
      "ItemProcessor": {
        "ProcessorConfig": {
          "Mode": "DISTRIBUTED",
          "ExecutionType": "STANDARD"
        },
        "StartAt": "BuildScheduleInput",
        "States": {
          "BuildScheduleInput": {
            "Type": "Pass",
            "Parameters": {
              "schedule_name.$": "States.Format('campaign-{}-{}', $.campaign_id, $.recipient.id)",
              "group_name.$": "States.Format('campaign-{}', $.campaign_id)",
              "schedule_expression.$": "States.Format('at({}T{}:00:00)', $.send_date_date, $.send_hour)",
              "timezone.$": "$.recipient.timezone",
              "target_input": {
                "FromEmailAddress": "campaigns@example.com",
                "Destination": {
                  "ToAddresses.$": "States.Array($.recipient.email)"
                },
                "Content": {
                  "Template": {
                    "TemplateName.$": "$.template_id",
                    "TemplateData.$": "States.JsonToString($.recipient.attributes)"
                  }
                }
              }
            },
            "Next": "CreateSchedule"
          },
          "CreateSchedule": {
            "Type": "Task",
            "Resource": "arn:aws:states:::aws-sdk:scheduler:createSchedule",
            "Retry": [
              {
                "ErrorEquals": [
                  "Scheduler.SdkClientException"
                ],
                "IntervalSeconds": 2,
                "MaxAttempts": 3,
                "BackoffRate": 2
              }
            ],
            "Parameters": {
              "Name.$": "$.schedule_name",
              "GroupName.$": "$.group_name",
              "ScheduleExpression.$": "$.schedule_expression",
              "ScheduleExpressionTimezone.$": "$.timezone",
              "FlexibleTimeWindow": {
                "Mode": "FLEXIBLE",
                "MaximumWindowInMinutes": 5
              },
              "Target": {
                "Arn": "arn:aws:scheduler:::aws-sdk:sesv2:sendEmail",
                "RoleArn": "arn:aws:iam::976764934189:role/CampaignFanOutRole-dev",
                "Input.$": "States.JsonToString($.target_input)",
                "RetryPolicy": {
                  "MaximumEventAgeInSeconds": 7200,
                  "MaximumRetryAttempts": 5
                }
              },
              "ActionAfterCompletion": "DELETE"
            },
            "ResultPath": null,
            "End": true
          }
        }
      },
      "ItemReader": {
        "Resource": "arn:aws:states:::s3:getObject",
        "ReaderConfig": {
          "InputType": "CSV",
          "CSVHeaderLocation": "FIRST_ROW"
        },
        "Parameters": {
          "Bucket.$": "$$.Execution.Input.recipient_bucket",
          "Key.$": "$$.Execution.Input.recipient_key"
        }
      },
      "ItemSelector": {
        "campaign_id.$": "$$.Execution.Input.campaign_id",
        "template_id.$": "$$.Execution.Input.template_id",
        "send_date_date.$": "$$.Execution.Input.send_date_date",
        "send_hour.$": "$$.Execution.Input.send_hour",
        "recipient": {
          "id.$": "$$.Map.Item.Value.id",
          "email.$": "$$.Map.Item.Value.email",
          "timezone.$": "$$.Map.Item.Value.timezone",
          "attributes": {
            "first_name.$": "$$.Map.Item.Value.first_name",
            "signup_date.$": "$$.Map.Item.Value.signup_date"
          }
        }
      },
      "MaxConcurrency": 1000,
      "ResultPath": null,
      "End": true
    }
  }
}

Alinhamento de concorrência com os limites da API do Amazon EventBridge Scheduler

O Distributed Map do Step Functions suporta até 10.000 execuções filhas simultâneas. Cada execução filha chama a API CreateSchedule diretamente, que possui um limite de taxa padrão de 5.000 TPS. Esse limite é suficiente para a maioria das campanhas. Se os volumes da sua campanha exigirem uma taxa de transferência maior, verifique suas cotas atuais no console do Service Quotas e solicite um aumento.

Para evitar limitação por throttling, defina MaxConcurrency abaixo da cota de TPS do CreateSchedule. Um valor de 2.500 fornece uma margem confortável para lidar com picos e novas tentativas, sem exigir uma alteração de cota. Para campanhas maiores, solicite um aumento por meio do AWS Service Quotas (ajustável para dezenas de milhares) e aumente o MaxConcurrency de acordo.

Cancelando uma campanha

Um grupo de agendamento é um recurso do Amazon EventBridge Scheduler usado para organizar agendamentos. Neste caso de uso, temos um grupo de agendamento por campanha. Se você precisar retirar uma campanha (erro no conteúdo, questão legal ou mudança de estratégia), pode cancelar todos os envios agendados dessa campanha excluindo o grupo de agendamento por completo. O código a seguir mostra como cancelar todos os envios pendentes de uma campanha:

def cancel_campaign(campaign_id):
    """Cancel all pending sends for a campaign by deleting its schedule group."""
    scheduler.delete_schedule_group(
        Name=f'campaign-{campaign_id}'
    )

Considerações operacionais

A passagem para produção introduz algumas preocupações de escalabilidade e confiabilidade que devem ser planejadas.

Lidando com picos de invocação no horário de entrega

Quando uma campanha em massa agenda milhões de mensagens para o mesmo horário, isso cria uma pressão em cascata em dois limites:

Limite de throttling de invocações do Amazon EventBridge Scheduler: o padrão é 1.000 TPS por região da AWS, e é ajustável para dezenas de milhares de TPS por meio do AWS Service Quotas. O Amazon EventBridge Scheduler colocará as invocações em fila internamente e fará novas tentativas com espera exponencial (exponential backoff) quando o alvo posterior aplicar throttling.
Cotas de envio do Amazon SES: sua conta do SES possui uma taxa de envio por segundo. Se a taxa efetiva de invocação exceder esse limite, as mensagens falharão com erros de throttling. Alinhe as cotas de envio do Amazon SES ao volume da sua campanha. Verifique sua cota atual do SES no console do Service Quotas e solicite um aumento antes de lançar campanhas grandes. Consulte as práticas recomendadas do Amazon SES para entregabilidade em escala.

Para lidar com um pico de invocação, recomendamos usar o recurso FlexibleTimeWindow do Amazon EventBridge Scheduler. Definir MaximumWindowInMinutes permite que o Amazon EventBridge Scheduler distribua as invocações em uma janela de tempo, em vez de dispará-las todas no segundo exato. Dimensione a janela com base na sua campanha: divida o total de agendamentos pelo seu TPS efetivo para determinar a distribuição mínima necessária. Por exemplo, 500.000 agendamentos a 5.000 TPS precisam de uma janela de pelo menos 2 minutos.

Modelo de custos

Você paga pelo Amazon EventBridge Scheduler com base no número de invocações.

Limpeza

Para evitar cobranças contínuas, exclua os recursos criados durante este passo a passo:

Exclua todos os grupos de agendamento criados em tempo de execução.
```
aws scheduler delete-schedule-group --name campaign-<campaign-id>
```

Exclua a máquina de estados do Step Functions.

aws stepfunctions delete-state-machine \
    --state-machine-arn arn:aws:states:us-east-1:<account-id>:stateMachine:CampaignFanOut

Observação: se você ainda tiver agendamentos ativos esperando para disparar, excluir o grupo de agendamento cancelará todos os envios pendentes.

Função do IAM para o Amazon EventBridge Scheduler e o Step Functions

A máquina de estados do Step Functions precisa de uma função de execução com permissões para criar agendamentos, enviar e-mails e passar a função para o serviço do Amazon EventBridge Scheduler. O Amazon EventBridge Scheduler precisa de permissões para chamar o SES. A política a seguir mostra as permissões combinadas para ambos os cenários:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPassRoleToScheduler",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::<ACCOUNT_ID>:role/CampaignFanOutRole",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "scheduler.amazonaws.com"
        }
      }
    },
    {
      "Sid": "AllowSESSend",
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail",
        "ses:SendTemplatedEmail"
      ],
      "Resource": "arn:aws:ses:<REGION>:<ACCOUNT_ID>:identity/campaigns@example.com"
    },
    {
      "Sid": "DistributedMapExecution",
      "Effect": "Allow",
      "Action": [
        "states:StartExecution",
        "states:DescribeExecution",
        "states:StopExecution"
      ],
      "Resource": [
        "arn:aws:states:<REGION>:<ACCOUNT_ID>:stateMachine:CampaignFanOut",
        "arn:aws:states:<REGION>:<ACCOUNT_ID>:execution:CampaignFanOut:*"
      ]
    },
    {
      "Sid": "ReadRecipientsBucket",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::campaign-recipients-<ACCOUNT_ID>",
        "arn:aws:s3:::campaign-recipients-<ACCOUNT_ID>/*"
      ]
    },
    {
      "Sid": "CreateSchedules",
      "Effect": "Allow",
      "Action": "scheduler:CreateSchedule",
      "Resource": "arn:aws:scheduler:<REGION>:<ACCOUNT_ID>:schedule/campaign-*"
    },
    {
      "Sid": "CreateScheduleGroups",
      "Effect": "Allow",
      "Action": "scheduler:CreateScheduleGroup",
      "Resource": "arn:aws:scheduler:<REGION>:<ACCOUNT_ID>:schedule-group/campaign-*"
    },
    {
      "Sid": "PassRoleToScheduler",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::<ACCOUNT_ID>:role/SchedulerCampaignRole",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "scheduler.amazonaws.com"
        }
      }
    }
  ]
}

Esta política restringe as ações scheduler:CreateSchedule e scheduler:CreateScheduleGroup a recursos com o prefixo campaign-*, seguindo os princípios de privilégio mínimo.

Uma condição restringe a permissão iam:PassRole para que ela só possa passar a função para o serviço do Amazon EventBridge Scheduler.

Conclusão

Nesta publicação, mostramos como usar o Amazon EventBridge Scheduler para personalizar a entrega de campanhas de e-mail para cada destinatário. Um sistema de campanha de e-mail tem dois problemas principais: decidir o que enviar e decidir quando enviar. A maioria das equipes complica demais o “quando” com infraestrutura de polling, jobs em lote e cadeias de filas. O Amazon EventBridge Scheduler condensa isso em uma única chamada de API CreateSchedule por destinatário.

Para começar, explore o Amazon EventBridge Scheduler no AWS Management Console. Confira os padrões do Serverless Land para mais de 20 padrões do Amazon EventBridge Scheduler e outros casos de uso além de campanhas de e-mail.

Tags sugeridas: Amazon EventBridge, arquitetura, eventos, modernização, Serverless.

Este conteúdo foi traduzido a partir da publicação original do blog, que pode ser encontrada aqui.

Autores

	Oluwaseun Ademuwagun é ISV Solutions Architect na Amazon Web Services.
	Serda Kasaci Yildirim é Sr. Solutions Architect na Amazon Web Services.
	Rana Kiziltoprak German é Sr. Technical Account Manager na Amazon Web Services.

Tradutores

Daniel Abib é Arquiteto de Soluções Sênior e Especialista em Amazon Bedrock na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e especialização em Machine Learning. Ele trabalha apoiando Startups, ajudando-os em sua jornada para a nuvem.
https://www.linkedin.com/in/danielabib/

Rodrigo Peres é Arquiteto de Soluções na AWS, com mais de 20 anos de experiência trabalhando com arquitetura de soluções, desenvolvimento de sistemas e modernização de sistemas legados.

O blog da AWS