Class: Postburner::Mailer

Inherits:
Job show all
Defined in:
app/models/postburner/mailer.rb

Overview

A tracked job for sending ActionMailer emails via Beanstalkd.

Provides a chainable API similar to ActionMailer for building and queueing email deliveries with full audit trail support.

Queue Configuration

By default, mailer jobs use the default_queue (typically ‘default’). You can route mailers to a dedicated queue using several approaches:

Via configuration (recommended)

Set default_mailer_queue in your postburner.yml or configuration:

# config/postburner.yml
production:
  default_mailer_queue: mailers

# Or programmatically
Postburner.configure do |config|
  config.default_mailer_queue = 'mailers'
end

Via queue! option (per-job override)

Override the queue when queueing a specific job:

Postburner::Mailer.delivery(UserMailer, :welcome)
  .with(user_id: 1)
  .queue!(queue: 'priority_mailers')

Via instance setter (per-job override)

Set the queue on the job instance before queueing:

job = Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1)
job.queue_name = 'priority_mailers'
job.queue!

Testing

Because Postburner::Mailer bypasses ActiveJob, Rails’ assert_enqueued_emails will not detect these jobs. Use assert_emails (which checks actual deliveries) or assert on the job record:

# Assert email was delivered (inline in test mode)
assert_emails 1 do
  Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!
end

# Assert job was processed
assert job.reload.processed_at

Examples:

Basic delivery (queued immediately)

Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!

Scheduled delivery at a specific time

Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(at: Time.current + 1.day)

Delayed delivery

Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(delay: 5.minutes)

Queue to specific queue

Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1).queue!(queue: 'bulk_mailers')

See Also:

Instance Attribute Summary

Attributes inherited from Job

#args, #attempt_count, #attempting_at, #attempts, #bkid, #duration, #errata, #error_count, #id, #lag, #log_count, #logs, #processed_at, #processing_at, #queued_at, #removed_at, #run_at, #sid, #type

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Job

#bk, #bk!, #bk=, #destroy, #destroy!, find_sti_class, #orphaned?

Methods included from Statistics

#elapsed_ms, #intended_at, #stats

Methods included from Execution

#perform!

Methods included from Insertion

#queue!, #requeue!, #will_insert?

Methods included from Commands

#delete!, #extend!, #kick!, #remove!

Methods included from Logging

#log, #log!, #log_exception, #log_exception!

Methods included from Properties

#priority, #retry_delay_for_attempt, #should_retry?, #ttr, #tube_name

Class Method Details

.delivery(mailer, action) ⇒ Postburner::Mailer

Build a new mailer job without persisting.

Examples:

job = Postburner::Mailer.delivery(UserMailer, :welcome)
job.with(user_id: 1).queue!

Parameters:

  • mailer (Class) —

    The ActionMailer class (e.g., UserMailer)

  • action (Symbol, String) —

    The mailer action/method name (e.g., :welcome)

Returns:



102
103
104
105
106
107
108
109
110
 
# File 'app/models/postburner/mailer.rb', line 102

def self.delivery(mailer, action)
  job = self.new(
    args: {
      mailer: mailer.to_s,
      action: action.to_s,
    }
  )
  job
end

.delivery!(mailer, action) ⇒ Postburner::Mailer

Build and persist a new mailer job.

Examples:

job = Postburner::Mailer.delivery!(UserMailer, :password_reset)
job.with!(token: reset_token)

Parameters:

  • mailer (Class) —

    The ActionMailer class (e.g., UserMailer)

  • action (Symbol, String) —

    The mailer action/method name (e.g., :welcome)

Returns:



121
122
123
124
125
 
# File 'app/models/postburner/mailer.rb', line 121

def self.delivery!(mailer, action)
  job = self.delivery(mailer, action)
  job.save!
  job
end

Instance Method Details

#action ⇒ Symbol?

Get the mailer action name.

Examples:

job.action  # => :welcome

Returns:

  • (Symbol, nil) —

    The mailer action as a symbol



192
193
194
 
# File 'app/models/postburner/mailer.rb', line 192

def action
  self.args['action']&.to_sym
end

#assemble ⇒ Mail::Message

Build the Mail::Message without sending.

Useful for testing or inspecting the email before delivery.

Examples:

Inspect email before sending

job = Postburner::Mailer.delivery(UserMailer, :welcome).with(user_id: 1)
mail = job.assemble
puts mail.subject  # => "Welcome!"
puts mail.to       # => ["user@example.com"]

Returns:

  • (Mail::Message) —

    The assembled email message



171
172
173
174
 
# File 'app/models/postburner/mailer.rb', line 171

def assemble
  mail = self.mailer.with(self.params).send(self.action)
  mail
end

#mailer ⇒ Class

Get the mailer class.

Examples:

job.mailer  # => UserMailer

Returns:

  • (Class) —

    The ActionMailer class



182
183
184
 
# File 'app/models/postburner/mailer.rb', line 182

def mailer
  self.args['mailer'].constantize
end

#params ⇒ Hash

Get the deserialized mailer parameters.

Examples:

job.params  # => { user_id: 1, locale: :en }

Returns:

  • (Hash) —

    The parameters passed via #with



202
203
204
 
# File 'app/models/postburner/mailer.rb', line 202

def params
  ::ActiveJob::Arguments.deserialize(self.args['params']).to_h
end

#perform(args) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Execute the mailer job.

Called by the Postburner worker. Assembles and delivers the email, logging progress at each step.

Parameters:

  • args (Hash) —

    Job arguments (unused, params stored in Job#args)



215
216
217
218
219
220
221
222
223
 
# File 'app/models/postburner/mailer.rb', line 215

def perform(args)
  self.log! "Building"
  mail = self.assemble

  self.log! "Delivering"
  mail.deliver_now

  self.log! "Delivered"
end

#queue_name ⇒ String

Returns the queue name for this mailer job.

Checks in order: instance override, default_mailer_queue config, then falls back to default_queue.

Examples:

Default behavior (uses default_mailer_queue or default_queue)

job = Postburner::Mailer.delivery(UserMailer, :welcome)
job.queue_name  # => 'mailers' (if configured) or 'default'

Instance override

job = Postburner::Mailer.delivery(UserMailer, :welcome)
job.queue_name = 'priority_mailers'
job.queue_name  # => 'priority_mailers'

Returns:

  • (String) —

    Queue name



86
87
88
89
90
91
 
# File 'app/models/postburner/mailer.rb', line 86

def queue_name
  @queue_name ||
    self.class.queue ||
    Postburner.configuration.default_mailer_queue ||
    Postburner.configuration.default_queue
end

#with(params = {}) ⇒ self

Set the mailer parameters without persisting.

Similar to ActionMailer’s #with method for parameterized mailers. Parameters are serialized using ActiveJob::Arguments for safe storage.

Examples:

Postburner::Mailer.delivery(UserMailer, :welcome)
  .with(user_id: 1, locale: :en)
  .queue!

Parameters:

  • params (Hash) (defaults to: {}) —

    Parameters to pass to the mailer

Returns:

  • (self) —

    Returns self for method chaining



139
140
141
142
143
144
 
# File 'app/models/postburner/mailer.rb', line 139

def with(params={})
  self.args.merge!(
    'params' => ::ActiveJob::Arguments.serialize(params)
  )
  self
end

#with!(params = {}) ⇒ self

Set the mailer parameters and persist immediately.

Examples:

job = Postburner::Mailer.delivery!(OrderMailer, :confirmation)
job.with!(order_id: order.id)

Parameters:

  • params (Hash) (defaults to: {}) —

    Parameters to pass to the mailer

Returns:

  • (self) —

    Returns self for method chaining



154
155
156
157
158
 
# File 'app/models/postburner/mailer.rb', line 154

def with!(params={})
  self.with(params)
  self.save!
  self
end