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 = "support@example.com"
 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