Sincerely

Introduction

Sincerely is a versatile Ruby gem designed for creating, delivering and monitoring email, sms or push notifications.

Table of Contents

1. Installation
2. Getting Started
3. Configuration
4. Usage
5. Notification model
6. Notification states
7. Callbacks
8. How to Run Tests
9. Guide for Contributing
10. How to Contact Us
11. License

Installation

Sincerely 1.0 works with Rails 6.0 onwards. Run:

bundle add sincerely

Getting Started

1. First, you need to run the install generator, which will create the config/sincerely.yml initializer file for you:

rails g sincerely:install

2. You need to generate and run a migration to create the notifications and notification_templates tables and the Notification and the NotificationTemplate model:

rails g sincerely:migration Notification

rails db:migrate

3. If you want to enable event callbacks you need to run the events task to create the sincerely_delivery_events and sincerely_engagements_events tables and the Sincerely::DeliveryEvent and Sincerely::EngagementEvent models:

rails g sincerely:events

rails db:migrate

Configuration

1. You need to set the notification model generated in the previous step by setting the notification_model_name option in the config/sincerely.yml file:

# config/sincerely.yml
defaults: &defaults
  notification_model_name: Notification

2. You need to set the delivery system for each delivery methods (email/sms/push) by setting the delivery_methods option in the config/sincerely.yml file. Please note that right now the gem supports only AWS SES email notification (Sincerely::DeliverySystems::EmailAwsSes module).

# config/sincerely.yml
defaults: &defaults
  delivery_methods:
    email:
      delivery_system: Sincerely::DeliverySystems::EmailAwsSes
      options:
        region: region
        access_key_id: your_access_key_id
        secret_access_key: your_secret_access_key
        configuration_set_name: config_set
    sms:

• region: the AWS region to connect to
• access_key_id: AWS access key id
• secret_access_key: AWS secret access key
• configuration_set_name: the name of the configuration set to use when sending the email, you don't need to specify the configuration set option if you don't want to handle SES email sending events

Sincerely uses the aws-sdk-sesv2 gem to send emails. See sesv2 for details.

Furthermore you need to configure Amazon SES to be able to send emails, see SES for details.

Usage

1. Once the email delivery method is configured you need to create an email template which is used to generate the email content:

Sincerely::Templates::EmailLiquidTemplate.create(
  name: 'test',
  subject: 'template for sending messages',
  sender: 'john.doe@gmail.com'
  html_content: 'hi {{name}}',
  text_content: 'hi {{name}}'
)

• name: unique id of the template
• subject: subject of the generated email (can be overwritten in the notification)
• sender: email address of the sender
• html_content: html content of the generated email, you can use the liquid syntax to use variables in the content, see liquid for details
• text_content: text content of the generated email, you can use the liquid syntax to use variables in the content, see liquid for details

2. You need to create the notification:

Notification.create(
  recipient: 'jane.doe@gmail.com',
  notification_type: 'email',
  template: Sincerely::Templates::EmailLiquidTemplate.first,
  delivery_options: {
    template_data: {
      name: 'John Doe'
    },
    subject: 'subject'
  }
)

• recipient: recipient of the notification
• notification_type: email/sms/push (please note that right now the gem supports only AWS SES email notifications)
• template: template to generate the notification content
• delivery_options: options for the associated template (EmailLiquidTemplate supports (i) the template_data option which contains the parameter hash for the liquid template defined in the html_content field of the associated template, (ii) the subject option which overwrites the subject defined in the associated template)

3. You need to send the notification:

notification.deliver

Notification model

• recipient: recipient (email or phone number) of the notification
• notification_type: email | sms | push
• delivery_options: options for the associated template
• delivery_system: associated delivery system
• delivery_state: state of the notification
• template_id: associated template
• sent_at: timestamp of the delivery
• message_id: message id generated by the delivery system
• error_message: error message if the notification is rejected by the delivery system

Notification states

• draft: default state, notification is not yet sent
• accepted: the send request was successful and the delivery system will attempt to deliver the message to the recipient’s mail server
• rejected: notification is rejected by the delivery system
• delivered: notification is successfully delivered by the delivery system
• bounced: notification is bounced (ie when an email cannot be delivered to the recipient)
• opened: notification is opened
• clicked: notification is clicked
• complained: notification is complained (ie when the recipient of your email marks your email as spam)

Please note that the notification state is updated only if the event callback is configured.

Callbacks

EmailAwsSes delivery system handles SES email sending events. To enable it make sure:

• you have run the events task described in the Getting Started section
• you have set the configuration_set_name option described in the Configuration section
• you have run the following task that generates the webhook controller for you

rails g sincerely:aws_ses_webhook_controller SES_WEBHOOK

Furthermore you need to configure Amazon SES to monitor email sending, see SES email sending events for details.

Once the webhook controller is in place, it will:

• update the state of the notifications
• create event records for the bounce/complaint/open/click events

Delivery events (delivery/bounce) fields:

• message_id: message id generated by the delivery system
• delivery_system: associated delivery system
• event_type: delivery | bounce
• recipient: recipient of the notification
• delivery_event_type: bounce type
• delivery_event_subtype: bounce subtype
• options: other event specific options (if any)
• timestamp: timestamp of the event

Engagement events (open/click/compaint) fields:

• message_id: message id generated by the delivery system
• delivery_system: associated delivery system
• event_type: open | click | compaint
• recipient: recipient of the notification
• ip_address: the recipient's IP address
• user_agent: the user agent of the device or email client
• link: the URL of the link that the recipient clicked
• feedback_type: complaint feedback type
• options: other event specific options (if any)
• timestamp: timestamp of the event

How to Run Tests