Module: AppEngine::Mail

Defined in:
lib/appengine-apis/mail.rb

Overview

App Engine applications can send email messages on behalf of the app’s administrators, and on behalf of users with Google Accounts. Apps use the Mail service to send email messages.

The Mail.send method sends an email message from the application. The From: address can be either the email address of a registered administrator (developer) of the application, or the current user if signed in with Google Accounts.

The following example sends an email message to the user as confirmation that the user created a new account with the application:

 class SignupController < Merb::Controller
   def confirm(self):
     user_address = params[:email_address"]
    confirmation_url = create_new_user_confirmation
    sender_address = "[email protected]"
    subject = "Confirm your registration"
    body = <<EOM
 Thank you for creating an account!  Please confirm your email address by
 clicking on the link below:

 #{confirmation_url}
 EOM

    AppEngine::Mail.send(sender_address, user_address, subject, body)
  end
end

Class Method Summary collapse

Class Method Details

.convert_mail_exceptions ⇒ Object

:nodoc:



142
143
144
145
146
147
148
149
150
 
# File 'lib/appengine-apis/mail.rb', line 142

def convert_mail_exceptions  # :nodoc:
  begin
    yield
  rescue java.lang.IllegalArgumentException => ex
    raise ArgumentError, ex.message
  rescue java.io.IOException => ex
    raise IOError, ex.message
  end
end

.create_java_message(options) ⇒ Object

Creates a Java MailService.Message object.

Supported options:

:atttachments

Attachments to send with this message. Should be a Hash of => “data” or an Array of [[“filename”, “data”], …].

:bcc

Must be a String or an Array of Strings if set.

:cc

Must be a String or an Array of Strings if set.

:html

The html body of the message. Must not be nil if text is nil.

:reply_to

Must be a valid email address if set.



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/appengine-apis/mail.rb', line 118

def create_java_message(options)
  options[:text_body] = options.delete(:text)
  options[:html_body] = options.delete(:html)
  attachments = options[:attachments]
  if attachments
    options[:attachments] = attachments.collect do |filename, data|
      MailService::Attachment.new(filename, data.to_java_bytes)
    end
  end
  [:to, :cc, :bcc].each do |key|
    value = options[key]
    options[key] = [value] if value.kind_of? String
  end
  message = MailService::Message.new
  options.each do |key, value|
    begin
      message.send("set_#{key}", value) if value
    rescue NameError
      raise ArgumentError, "Invalid option #{key.inspect}."
    end
  end
  return message
end

.send(sender, to, subject, text, options = {}) ⇒ Object

Sends an email.

The message will be delivered asynchronously, and delivery problems will result in a bounce to the specified sender.

Args:

sender

The From: field of the email. Must correspond to the valid email address of one of the admins for this application, or to the email address of the currently logged-in user.

to

Message recipient(s). Should be an email address, or an Array of email addresses.

subject

Subject of the message.

text

Plain text body of the message. To send an HTML only email, set text to nil and use the :html option.

options

See #create_java_message for supported options.



70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/appengine-apis/mail.rb', line 70

def send(sender, to, subject, text, options={})
  orig_options = options
  options = {
    :sender => sender,
    :to => to || [],
    :subject => subject,
    :text => text
  }
  options.merge!(orig_options)
  message = create_java_message(options)
  convert_mail_exceptions { service.send(message) }
end

.send_to_admins(sender, subject, text, options = {}) ⇒ Object

Sends an email alert to all admins of an application.

The message will be delivered asynchronously, and delivery problems will result in a bounce to the admins.

Args:

sender

The From: field of the email. Must correspond to the valid email address of one of the admins for this application, or to the email address of the currently logged-in user.

subject

Subject of the message.

text

Plain text body of the message. To send an HTML only email, set text to nil and use the :html option.

options

See #create_java_message for supported options.



96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/appengine-apis/mail.rb', line 96

def send_to_admins(sender, subject, text, options={})
  orig_options = options
  options = {
    :sender => sender,
    :subject => subject,
    :text => text
  }
  options.merge!(orig_options)
  message = create_java_message(options)
  convert_mail_exceptions { service.send_to_admins(message) }
end

.service ⇒ Object

:nodoc:



152
153
154
 
# File 'lib/appengine-apis/mail.rb', line 152

def service  # :nodoc:
  @service ||= MailServiceFactory.mail_service
end

.service=(service) ⇒ Object

:nodoc:



156
157
158
 
# File 'lib/appengine-apis/mail.rb', line 156

def service=(service)  # :nodoc:
  @service = service
end