Class: Hanami::Mailer::Delivery::Result

Inherits:
Object
  • Object
show all
Defined in:
lib/hanami/mailer/delivery/result.rb

Overview

Represents the outcome of a message delivery attempt.

This is the base class for delivery results. Delivery methods return an instance of this class (or a subclass) from their #call method. Third-party delivery methods are encouraged to subclass this and add any service-specific attributes they need.

Examples:

Checking a result

result = mailer.deliver(user: user)
if result.success?
  log.info "Delivered to #{result.message.to.join(', ')}"
else
  log.error "Delivery failed: #{result.error}"
end

A third-party delivery method returning a richer result

class Delivery::Postmark::Result < Hanami::Mailer::Delivery::Result
  attr_reader :message_id, :submitted_at

  def initialize(message_id:, submitted_at: nil, **)
    super(**)
    @message_id   = message_id
    @submitted_at = submitted_at
  end
end

Since:

  • 3.0.0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message:, response: nil, error: nil) ⇒ Result

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.

Returns a new instance of Result.

Parameters:

  • message (Hanami::Mailer::Message) —

    the prepared message

  • response (Object, nil) (defaults to: nil) —

    the raw response from the delivery method

  • error (#to_s, nil) (defaults to: nil) —

    the error, if delivery failed. The result's success status is derived from its absence.

Since:

  • 3.0.0



73
74
75
76
77
 
# File 'lib/hanami/mailer/delivery/result.rb', line 73

def initialize(message:, response: nil, error: nil)
  @message  = message
  @response = response
  @error    = error
end

Instance Attribute Details

#error ⇒ #to_s? (readonly)

The error that occurred during delivery, if delivery failed.

This is nil for a successful delivery. For a failed delivery it is a truthy object describing the error. For SMTP deliveries, this will be an exception raised during delivery, but delivery methods are free to represent failures with any object that responds to #to_s, allowing for objects that carry richer error details.

Returns:

  • (#to_s, nil) —

    the error if delivery failed, or nil if it succeeded

Since:

  • 3.0.0



65
66
67
 
# File 'lib/hanami/mailer/delivery/result.rb', line 65

def error
  @error
end

#message ⇒ Hanami::Mailer::Message (readonly)

The prepared message that was (or was attempted to be) delivered.

Returns:

Since:

  • 3.0.0



40
41
42
 
# File 'lib/hanami/mailer/delivery/result.rb', line 40

def message
  @message
end

#response ⇒ Object? (readonly)

The raw return value from the delivery method, if any.

For SMTP delivery this will be the Mail::Message object. For test delivery this will be nil. The exact type is delivery-method-specific; consult the documentation for the delivery method you are using.

Returns:

  • (Object, nil)

Since:

  • 3.0.0



52
53
54
 
# File 'lib/hanami/mailer/delivery/result.rb', line 52

def response
  @response
end

Instance Method Details

#failure? ⇒ Boolean

Returns true if delivery failed.

Returns:

  • (Boolean)

Since:

  • 3.0.0



95
96
97
 
# File 'lib/hanami/mailer/delivery/result.rb', line 95

def failure?
  !success?
end

#success? ⇒ Boolean

Returns true if delivery succeeded.

Returns:

  • (Boolean)

Since:

  • 3.0.0



85
86
87
 
# File 'lib/hanami/mailer/delivery/result.rb', line 85

def success?
  error.nil?
end