Skip to main content
Version: 0.4

Email callbacks

Callbacks enable you to define logic that is triggered at different stages of an email's lifecycle. This document covers the available callbacks and introduces you to the associated API, which you can use to define hooks in your emails.

Overview

As stated above, callbacks are methods that will be called when specific events occur for a specific email instance. They need to be registered explicitly in your email classes.

Registering a callback is as simple as calling the right callback macro (eg. #before_deliver) with a symbol of the name of the method to call when the callback is executed.

For example, the following email leverages the #after_deliver callback in order to emit a specific StatsD metric:

require "statsd"

statsd = Statsd::Client.new

class WelcomeEmail < Marten::Email
from "[email protected]"
to @user.email
subject "Hello!"
template_name "emails/welcome_email.html"

after_deliver :emit_delivered_welcome_email_metric

def initialize(@user : User)
end

private def emit_delivered_welcome_email_metric
statsd.increment "email.welcome.delivered", tags: ["app:myapp"]
end
end

Available callbacks

before_deliver

before_deliver callbacks are executed before an email is delivered (as part of the email's #deliver method). For example, this capability can be leveraged to mutate the considered email instance before the actual email gets delivered:

class WelcomeEmail < Marten::Email
from "[email protected]"
to @user.email
subject "Hello!"
template_name "emails/welcome_email.html"

before_deliver :set_header

def initialize(@user : User)
end

private def set_header
headers["X-Debug"] = "True" if Marten.env.staging?
end
end

after_deliver

after_deliver callbacks are executed after an email is delivered (as part of the email's #deliver method). For example, such callbacks can be leveraged to increment email-specific metrics:

require "statsd"

statsd = Statsd::Client.new

class WelcomeEmail < Marten::Email
from "[email protected]"
to @user.email
subject "Hello!"
template_name "emails/welcome_email.html"

after_deliver :emit_delivered_welcome_email_metric

def initialize(@user : User)
end

private def emit_delivered_welcome_email_metric
statsd.increment "email.welcome.delivered", tags: ["app:myapp"]
end
end

before_render

before_render callbacks are invoked prior to rendering a template when generating the HTML or text body of the email. This means that these callbacks are executed when calling either the #deliver, #html_body, or #text_body methods.

Typically, these callbacks can be used to add new variables to the global email template context, in order to make them available to the template runtime. This can be useful if your email has some instance variables that you want to expose to your email template. For example:

class WelcomeEmail < Marten::Email
from "[email protected]"
to @user.email
subject "Hello!"
template_name "emails/welcome_email.html"

before_render :prepare_context

def initialize(@user : User)
end

private def prepare_context
context[:user] = @user
end
end