Barong mailer

Mailer in the barong app is a deamon listening events from RabbitMQ, it renders emails using templates in the language set in user profile (if possible) and send emails.

This guide explains the basics of using mailer to manage events from rubykube Event API.

It is usually used by following components:

Read more about Peatio Event API. Read more about Barong Event API.

Concepts

An Event is a message produced to message broker in RFC7515.

Events have the following structure:

{
  "payload": "string",
  "signatures": [
    {
      "header": {
        "kid":"string"
      },
      "protected":"string",
      "signature":"string"
    }
  ]
}

Deep dive

By specification defined in RFC7515 we can build a JSON Web Token.

After parsing of prebuilt JWT, you will receive this payload with this structure.

{
  "iss": "string",
  "jti": "string",
  "iat": 1567777420,
  "exp": 1567777480,
  "event": {
    "record": {
      "user": {
        "uid": "string",
        "email": "string",
      },
      "language": "string",
    },
    "name": "string"
  }
}

Note: All events should be properly signed using RS256 private key.

Mailer validates the signature of each upcoming event.

Further, we will see that mailer user can work with this payload directly.

{
  "record": {
    "user": {
      "uid": "UID12345678",
      "email": "johndoe@example.com"
    },
    "language": "EN"
  },
  "changes": {},
  "name": "string"
}

Run

Variable Description Required Default
BARONG_EVENT_API_RABBITMQ_HOST Host of RabbitMQ daemon no localhost
BARONG_EVENT_API_RABBITMQ_PORT Port of RabbitMQ daemon no 5672
BARONG_EVENT_API_RABBITMQ_USERNAME RabbitMQ username no guest
BARONG_EVENT_API_RABBITMQ_PASSWORD RabbitMQ password no guest
BARONG_SMTP_PASSWORD Password used for auth to SMTP yes
BARONG_SMTP_PORT Post of SMTP server no 25
BARONG_SMTP_HOST Host of SMTP server no smtp.sendgrid.net
BARONG_SMTP_USER User used for auth to SMTP no apikey
BARONG_SENDER_EMAIL Email address of mail sender yes
BARONG_SENDER_NAME Name of mail sender no Barong
./bin/mailer --config=config/mailer.yml run

Mailer creates one queue and bind pre-defined exchanges to it.

Configuration

Mailer is a flexible tool, you can cusomize alomost everything. Biggest part of customizations defined in mailer.yml, but you can also modify templates.

Each Event API provider uses own AMQP exchange and algorithm to sign payload.

exchanges:
  barong:
    name: barong.events.system
    signer: peatio

Using keychain algorithms and defined public keys for each provider mailer will validate the data.

keychain:
  barong:
    algorithm: RS256
    value: "public_key"

In events you may define any event type from Event API providers and prepare email template for it.

events:
  - name: Email Confirmation
    key: user.email.confirmation.token
    exchange: barong
    templates:
      EN:
        subject: Registration Confirmation
        template_path: email_confirmation.en.html.erb
      RU:
        subject: Подтверждение Регистрации
        template_path: email_confirmation.ru.html.erb

The simpliest mailer configuration will look like this one:

keychain:
  barong:
    algorithm: RS256
    value: "changeme"
  peatio:
    algorithm: RS256
    value: "changeme"

exchanges:
  barong:
    name: barong.events.system
    signer: barong

events:
  - name: Email Confirmation
    key: user.email.confirmation.token
    exchange: barong_system
    templates:
      en:
        subject: Registration Confirmation
        template_path: email_confirmation.en.html.erb
      ru:
        subject: Подтверждение Регистрации
        template_path: email_confirmation.ru.html.erb

Templates

Mailer exposes few variables for usage inside the templates.

Variable Description
@user User related to this email
@record Created user up-to-date attributes.
@changes The changed user attributes and their values

User

User with related profile.

Variable
uid Unique user id
email User email
role User role
level User KYC level
state State of user's account
referral_id UID of referrer
profile Information about KYC profile

Record

Record always containes UID and other attributes, that's why we can also expose user, by searching with unique user id.

Example:

record: {
  uid: "ID30DD0DD986",
  email: "example@barong.io",
  role: "member",
  level: 1,
  otp: false,
  state: "pending",
  created_at: "2019-01-28T08:35:29Z",
  updated_at: "2019-01-28T08:35:29Z"
}

Changes

When entity changed, this will contain attributes before an udpate.

Example:

changes: {
  level: 0
}