mailer

README

mailer

Mailer is a service for rendering and sending email based on Golang Template with the help of MJML.

Getting Started

Golang binary is built with static link. You can download it directly from the GitHub Release page or build it by yourself by cloning this repo and running make.

A Docker image is available for amd64, arm and arm64 platforms on Docker Hub: vibioh/mailer.

You can configure app by passing CLI args or environment variables (cf. Usage section). CLI override environment variables.

You'll find a Kubernetes exemple in the infra/ folder, using my app chart

MJML

In order to use the MJML converter, you need to register to MJML API for having credentials or provided a compliant API like mjml-api.

Features

• Golang templating ease-of-use and performance
• MJML conversion on-the-fly
• Read-only container
• OpenTelemetry
• Configurable logger with JSON support

Templating & fixtures

Templates are read from the -templates option dir. You can have a look at the hello world example provided in this repository. Every files with *.html extension is parsed as a template.

Fixtures for each template are found from the directory where the template is. The default fixture is a file named default.json.

HTTP or AMQP Client

mailer is capable to render and send email in a synchrone manner with the HTTP endpoint. If any action has an error (parsing, rendering, converting, sending), the HTTP response will be in error.

It can also send email in an asynchronous way with AMQP. If an error occurs, the dead-letter queue will be processed every hour and a message will be processed at most 3 times before being dropped.

Sending email

The only provider implemented for sending emails is via the SMTP protocol. This quite-old protocol is the broader compatible: you can connect it to Postfix, to SMTP providers (e.g. MailGun, SendGrid) and is more resilient than an vendor-specific HTTP endpoint.

Client usage

You can reach HTTP or AMQP endpoints directly or use the provided package client to send email easily from you Golang application. You can find a full usage example in cmd/client/client.go

Endpoints

• GET /render/: list available templates, in JSON format

• GET /render/{templateName}?fixture={fixtureName}: render templateName as HTML with given fixtureName (default by default)

• GET /fixtures/{templateName}/: list available fixtures for given templateName, in JSON format

• POST /render/{templateName}?from={senderEmail}&sender={senderName}&subject={emailSubject}&to={recipient}: render {templateName} with data from JSON payload in body and send it with the given parameters. The emailSubject can be a Golang template. The to parameters can be passed multiple times.

• GET /health: healthcheck of server, always respond okStatus (default 204)

• GET /ready: checks external dependencies availability and then respond okStatus (default 204) or 503 during graceDuration when SIGTERM is received

• GET /version: value of VERSION environment variable

Usage

The application can be configured by passing CLI args described below or their equivalent as environment variable. CLI values take precedence over environments variables.

Be careful when using the CLI values, if someone list the processes on the system, they will appear in plain-text. Pass secrets by environment variables: it's less easily visible.

Usage of mailer:
  --address            string    [server] Listen address ${MAILER_ADDRESS}
  --amqpExchange       string    [amqp] Exchange name ${MAILER_AMQP_EXCHANGE} (default "mailer")
  --amqpExclusive                [amqp] Queue exclusive mode (for fanout exchange) ${MAILER_AMQP_EXCLUSIVE} (default false)
  --amqpMaxRetry       uint      [amqp] Max send retries ${MAILER_AMQP_MAX_RETRY} (default 3)
  --amqpPrefetch       int       [amqp] Prefetch count for QoS ${MAILER_AMQP_PREFETCH} (default 1)
  --amqpQueue          string    [amqp] Queue name ${MAILER_AMQP_QUEUE} (default "mailer")
  --amqpRetryInterval  duration  [amqp] Interval duration when send fails ${MAILER_AMQP_RETRY_INTERVAL} (default 1h0m0s)
  --amqpRoutingKey     string    [amqp] RoutingKey name ${MAILER_AMQP_ROUTING_KEY}
  --amqpURI            string    [amqp] Address in the form amqps?://<user>:<password>@<address>:<port>/<vhost> ${MAILER_AMQP_URI}
  --cert               string    [server] Certificate file ${MAILER_CERT}
  --corsCredentials              [cors] Access-Control-Allow-Credentials ${MAILER_CORS_CREDENTIALS} (default false)
  --corsExpose         string    [cors] Access-Control-Expose-Headers ${MAILER_CORS_EXPOSE}
  --corsHeaders        string    [cors] Access-Control-Allow-Headers ${MAILER_CORS_HEADERS} (default "Content-Type")
  --corsMethods        string    [cors] Access-Control-Allow-Methods ${MAILER_CORS_METHODS} (default "GET")
  --corsOrigin         string    [cors] Access-Control-Allow-Origin ${MAILER_CORS_ORIGIN} (default "*")
  --csp                string    [owasp] Content-Security-Policy ${MAILER_CSP} (default "default-src 'self'; base-uri 'self'; style-src 'self' 'unsafe-inline' fonts.googleapis.com; font-src fonts.gstatic.com; img-src 'self' data: http://i.imgur.com grafana.com https://ketchup.vibioh.fr/images/")
  --frameOptions       string    [owasp] X-Frame-Options ${MAILER_FRAME_OPTIONS} (default "deny")
  --graceDuration      duration  [http] Grace duration when SIGTERM received ${MAILER_GRACE_DURATION} (default 30s)
  --hsts                         [owasp] Indicate Strict Transport Security ${MAILER_HSTS} (default true)
  --idleTimeout        duration  [server] Idle Timeout ${MAILER_IDLE_TIMEOUT} (default 2m0s)
  --key                string    [server] Key file ${MAILER_KEY}
  --loggerJson                   [logger] Log format as JSON ${MAILER_LOGGER_JSON} (default false)
  --loggerLevel        string    [logger] Logger level ${MAILER_LOGGER_LEVEL} (default "INFO")
  --loggerLevelKey     string    [logger] Key for level in JSON ${MAILER_LOGGER_LEVEL_KEY} (default "level")
  --loggerMessageKey   string    [logger] Key for message in JSON ${MAILER_LOGGER_MESSAGE_KEY} (default "msg")
  --loggerTimeKey      string    [logger] Key for timestamp in JSON ${MAILER_LOGGER_TIME_KEY} (default "time")
  --mjmlPassword       string    [mjml] Secret Key or Basic Auth password ${MAILER_MJML_PASSWORD}
  --mjmlURL            string    [mjml] MJML API Converter URL ${MAILER_MJML_URL} (default "https://api.mjml.io/v1/render")
  --mjmlUsername       string    [mjml] Application ID or Basic Auth username ${MAILER_MJML_USERNAME}
  --okStatus           int       [http] Healthy HTTP Status code ${MAILER_OK_STATUS} (default 204)
  --port               uint      [server] Listen port (0 to disable) ${MAILER_PORT} (default 1080)
  --readTimeout        duration  [server] Read Timeout ${MAILER_READ_TIMEOUT} (default 5s)
  --shutdownTimeout    duration  [server] Shutdown Timeout ${MAILER_SHUTDOWN_TIMEOUT} (default 10s)
  --smtpAddress        string    [smtp] Address ${MAILER_SMTP_ADDRESS} (default "localhost:25")
  --smtpHost           string    [smtp] Plain Auth host ${MAILER_SMTP_HOST} (default "localhost")
  --smtpPassword       string    [smtp] Plain Auth Password ${MAILER_SMTP_PASSWORD}
  --smtpUsername       string    [smtp] Plain Auth Username ${MAILER_SMTP_USERNAME}
  --telemetryRate      string    [telemetry] OpenTelemetry sample rate, 'always', 'never' or a float value ${MAILER_TELEMETRY_RATE} (default "always")
  --telemetryURL       string    [telemetry] OpenTelemetry gRPC endpoint (e.g. otel-exporter:4317) ${MAILER_TELEMETRY_URL}
  --templates          string    [mailer] Templates directory ${MAILER_TEMPLATES} (default "./templates/")
  --url                string    [alcotest] URL to check ${MAILER_URL}
  --userAgent          string    [alcotest] User-Agent for check ${MAILER_USER_AGENT} (default "Alcotest")
  --writeTimeout       duration  [server] Write Timeout ${MAILER_WRITE_TIMEOUT} (default 10s)