Class: AWS::SimpleEmailService

Inherits:
Object
  • Object
show all
Includes:
Core::ServiceInterface
Defined in:
lib/aws/simple_email_service.rb,
lib/aws/simple_email_service/client.rb,
lib/aws/simple_email_service/errors.rb,
lib/aws/simple_email_service/quotas.rb,
lib/aws/simple_email_service/request.rb,
lib/aws/simple_email_service/identity.rb,
lib/aws/simple_email_service/identity_collection.rb,
lib/aws/simple_email_service/email_address_collection.rb

Overview

This class is the starting point for working with Amazon SimpleEmailService (SES).

To use Amazon SimpleEmailService you must first sign up here

For more information about Amazon SimpleEmailService:

Credentials

You can setup default credentials for all AWS services via AWS.config:

AWS.config(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Or you can set them directly on the SimpleEmailService interface:

ses = AWS::SimpleEmailService.new(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Rails

If you want to use Amazon SimpleEmailService to send email from your Rails application you just need to do 2 things:

  1. Configure your AWS credentials with config

  2. Set SES as the delivery method:

config.action_mailer.delivery_method = :amazon_ses

This has only been tested with Rails 2.3 and Rails 3.0.

Identities

Before you can send emails, you need to verify one or more identities. Identities are email addresses or domain names that you have control over. Until you have requested production access you will only be able to send emails to and from verified email addresses and domains.

Verifying Email Addresses

You can verify an email address for sending/receiving emails using the identities collection.

identity = ses.identities.verify('[email protected]')
identity.verified? #=> false

You will be sent an email address with a link. Follow the link to verify the email address.

Verifying Domains

You can also verify an entire domain for sending and receiving emails.

identity = ses.identities.verify('yourdomain.com')
identity.verification_token
#=> "216D+lZbhUL0zOoAkC83/0TAl5lJSzLmzsOjtXM7AeM="

You will be expected to update the DNS records for your domain with the given verification token. See the service documentation for more details.

Listing Identities

You can enumerate all identities:

ses.identities.map(&:identity)
#=> ['[email protected]', 'somedomain.com']

You can filter the types of identities enumerated:

domains = ses.identities.domains.map(&:identity)
email_addresses = ses.identities.email_addresses.map(&:identity)

You can get the verification status and token from identities as well.

# for an email address
identity = ses.identities['[email protected]']
identity.verified? #=> true/false

# for a domain
identity = ses.identities['yourdomain.com']
identity.verified? #=> true/false
identity.verification_token #=> '...'

Sending Email

To send a basic email you can use #send_email.

ses.send_email(
  :subject => 'A Sample Email',
  :from => '[email protected]',
  :to => '[email protected]',
  :body_text => 'Sample email text.',
  :body_html => '<h1>Sample Email</h1>')

If you need to send email with attachments or have other special needs that send_email does not support you can use #send_raw_email.

ses.send_raw_email(<<EMAIL)
Subject: A Sample Email
From: [email protected]
To: [email protected]

Sample email text.
EMAIL

If you prefer, you can also set the sender and recipient in ruby when sending raw emails:

ses.send_raw_email(<<EMAIL, :to => '[email protected]', :from => '[email protected]')
Subject: A Sample Email

Sample email text.
EMAIL

Quotas

Based on several factors, Amazon SES determines how much email you can send and how quickly you can send it. These sending limits are defined as follows:

  • :max_send_rate - Maximum number of emails you can send per second.

  • :max_24_hour_send - Maximum number of emails you can send in a 24-hour period.

To get your current quotas (and how many emails you have sent in the last 24 hours):

ses.quotas
# => {:max_24_hour_send=>200, :max_send_rate=>1.0, :sent_last_24_hours=>22}

Statistics

You can get statistics about individual emails:

ses.statistics.each do |stats|
  puts "Sent: #{stats[:sent]}"
  puts "Delivery Attempts: #{stats[:delivery_attempts]}"
  puts "Rejects: #{stats[:rejects]}"
  puts "Bounces: #{stats[:bounces]}"
  puts "Complaints: #{stats[:complaints]}"
end

Defined Under Namespace

Modules: Errors Classes: Client, EmailAddressCollection, Identity, IdentityCollection, Quotas

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Core::ServiceInterface

#initialize, #inspect

Instance Attribute Details

#client ⇒ Client (readonly)

Returns the low-level SimpleEmailService client object.

Returns:

  • (Client) —

    the low-level SimpleEmailService client object



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/aws/simple_email_service.rb', line 173

class SimpleEmailService

  AWS.register_autoloads(self, 'aws/simple_email_service') do
    autoload :Client,                 'client'
    autoload :Errors,                 'errors'
    autoload :EmailAddressCollection, 'email_address_collection'
    autoload :Identity,               'identity'
    autoload :IdentityCollection,     'identity_collection'
    autoload :Quotas,                 'quotas'
    autoload :Request,                'request'
  end

  include Core::ServiceInterface

  # @note This method is deprecated.  Use {#identities} instead.
  # @return [EmailAddressCollection] Returns a collection that represents
  #   all of the verified email addresses for your account.
  def email_addresses
    EmailAddressCollection.new(:config => config)
  end

  # @return [IdentityCollection]
  def identities
    IdentityCollection.new(:config => config)
  end

  # Sends an email.  
  #
  #   ses.send_email(
  #     :subject => 'A Sample Email',
  #     :to => '[email protected]', 
  #     :from => '[email protected]',
  #     :body_text => 'sample text ...',
  #     :body_html => '<p>sample text ...</p>')
  #
  # You can also pass multiple email addresses for the +:to+, +:cc+, 
  # +:bcc+ and +:reply_to+ options.  Email addresses can also be 
  # formatted with names.
  #
  #   ses.send_email(
  #     :subject => 'A Sample Email',
  #     :to => ['"John Doe" <[email protected]>', '"Jane Doe" <[email protected]>'],
  #     :from => '[email protected]',
  #     :body_text => 'sample text ...')
  #
  # @param [Hash] options
  # @option options [required,String] :subject The subject of the message.
  #   A short summary of the content, which will appear in the #
  #   recipient's inbox.
  # @option options [required,String] :from The sender's email address.
  # @option options [String,Array] :to The address(es) to send the email to.
  # @option options [String,Array] :cc The address(es) to cc (carbon copy)
  #   the email to.
  # @option options [String,Array] :bcc The address(es) to bcc (blind
  #   carbon copy) the email to.
  # @option options [String,Array] :reply_to The reply-to email address(es)
  #   for the message. If the recipient replies to the message, each 
  #   reply-to address will receive the reply.
  # @option options [String] :return_path The email address to which 
  #   bounce notifications are to be forwarded. If the message cannot be
  #   delivered to the recipient, then an error message will be returned
  #   from the recipient's ISP; this message will then be forwarded to
  #   the email address specified by the +:return_path+ option.
  # @option options [String] :body_text The email text contents.
  #   You must provide +:body_text+, +:body_html+ or both.
  # @option options [String] :body_html The email html contents.
  #   You must provide +:body_text+, +:body_html+ or both.
  # @option options [String] :subject_charset The character set of the 
  #   +:subject+ string.  If the text must contain any other characters,
  #   then you must also specify the character set. Examples include 
  #   UTF-8, ISO-8859-1, and Shift_JIS. Defaults to 7-bit ASCII.
  # @option options [String] :body_text_charset The character set of the
  #   +:body_text+ string.  If the text must contain any other characters,
  #   then you must also specify the character set. Examples include 
  #   UTF-8, ISO-8859-1, and Shift_JIS. Defaults to 7-bit ASCII.
  # @option options [String] :body_html_charset The character set of the
  #   +:body_html+ string.  If the text must contain any other characters,
  #   then you must also specify the character set. Examples include 
  #   UTF-8, ISO-8859-1, and Shift_JIS. Defaults to 7-bit ASCII.
  # @option options [String] :body_html
  # @return [nil]
  def send_email options = {}

      require_each(options, :subject, :from)
      require_one_of(options, :to, :cc, :bcc)
      require_one_of(options, :body_text, :body_html)

    # these three options can be passed strings or arrays of strings,
    # but the service requires them in a list (array)
    [:to, :cc, :bcc, :reply_to].each do |key|
      if options[key]
        options[key] = [options[key]].flatten
      end
    end

    accepted_options = {
      :subject           => %w(message subject data),
      :subject_charset   => %w(message subject charset),
      :to                => %w(destination to_addresses),
      :cc                => %w(destination cc_addresses),
      :bcc               => %w(destination bcc_addresses),
      :from              => %w(source),
      :reply_to          => %w(reply_to_addresses),
      :return_path       => %w(return_path),
      :body_text         => %w(message body text data),
      :body_text_charset => %w(message body text charset),
      :body_html         => %w(message body html data),
      :body_html_charset => %w(message body html charset),
    }

    client.send_email(nest_options(options, accepted_options))
    nil

  end

  # Sends a raw email (email message, with header and content specified). 
  # Useful for sending multipart MIME emails.  The raw text of the message
  # must comply with Internet email standards; otherwise, the message 
  # cannot be sent.
  #
  #   raw = <<-EMAIL
  #   Date: Wed, 1 Jun 2011 09:13:07 -0700
  #   Subject: A Sample Email
  #   From: "John Doe" <[email protected]>
  #   To: "Jane Doe" <[email protected]>
  #   Accept-Language: en-US
  #   Content-Language: en-US
  #   Content-Type: text/plain; charset="utf-8"
  #   Content-Transfer-Encoding: base64
  #   MIME-Version: 1.0
  #
  #   c2FtcGxlIHRleHQNCg==
  #   EMAIL
  #
  #   ses.send_raw_email(raw)
  #
  # Amazon SES has a limit on the total number of recipients per 
  # message: The combined number of To:, CC: and BCC: email addresses 
  # cannot exceed 50. If you need to send an email message to a larger 
  # audience, you can divide your recipient list into groups of 50 or 
  # fewer, and then call Amazon SES repeatedly to send the message to 
  # each group.
  #
  # @param [required, String] raw_message The raw text of the message. 
  #   You can pass in any object whos #to_s returns a valid formatted
  #   email (e.g. ruby Mail gem).  The raw message should:
  #   * Contain a header and a body, separated by a blank line
  #   * Contain all required internet email headers
  #   * Each part of a multipart MIME message must be formatted properly
  #   * MIME content types must be among those supported by Amazon SES. 
  #     Refer to the Amazon SES Developer Guide for more details.
  #   * Use content that is base64-encoded, if MIME requires it
  # @option options [String,Array] :to One or more email addresses to
  #   send the email to.
  # @option options [String] :from The sender's email address.  
  #   If you specify the :from option, then bounce notifications and 
  #   complaints will be sent to this email address. This takes 
  #   precedence over any Return-Path header that you might include in 
  #   the +raw_message+.
  # @return [nil]
  def send_raw_email raw_message, options = {}

    send_opts = {}
    send_opts[:raw_message] = {}
    send_opts[:raw_message][:data] = raw_message.to_s
    send_opts[:source] = options[:from] if options[:from]

    if raw_message.respond_to?(:destinations)
      send_opts[:destinations] = raw_message.destinations
    end
    send_opts[:destinations] = [options[:to]].flatten if options[:to]

    client.send_raw_email(send_opts)
    nil

  end

  # for compatability with ActionMailer
  alias_method :deliver, :send_raw_email
  alias_method :deliver!, :send_raw_email

  # @example
  #
  #   ses.quotas
  #   # {:max_24_hour_send=>200, :max_send_rate=>1.0, :sent_last_24_hours=>22}
  #
  # @return [Hash] Returns a hash of SES quotas and limits.
  def quotas
    Quotas.new(:config => config).to_h
  end

  # Returns an array of email statistics. Each object in this array is a 
  # hash with the following keys:
  #
  # * +:delivery_attempts+
  # * +:rejects+
  # * +:bounces+
  # * +:complaints+
  # * +:timestamp+
  #
  # @return [Array of Hashes] An array of email statistic hashes.
  def statistics
    response = client.get_send_statistics
    response.data[:send_data_points].collect do |data|
      {
        :sent => data[:timestamp],
        :delivery_attempts => data[:delivery_attempts],
        :rejects => data[:rejects],
        :bounces => data[:bounces],
        :complaints => data[:complaints],
      }
    end
  end

  # @private
  protected
  def require_one_of options, *keys
    unless keys.any?{|key| options[key] }
      parts = keys.collect{|key| ":#{key}" }.join(', ')
      raise ArgumentError, "you must provide at least one of #{parts}" 
    end
  end

  # @private
  protected
  def require_each options, *keys
    keys.each do |key|
      unless options[key]
        raise ArgumentError, "missing required option :#{key}"
      end
    end
  end

  # @private
  protected
  def nest_options options, accepted_options

    send_opts = {}
    accepted_options.each_pair do |option, keys|
      next unless options[option]
      hash = send_opts
      keys.collect{|k| k.to_sym }.each do |key|
        hash[key] = {} unless hash[key]
        if keys.last == key.to_s
          hash[key] = options[option]
        else
          hash = hash[key]
        end
      end
    end

    send_opts
  end

end

Instance Method Details

#email_addresses ⇒ EmailAddressCollection

Note:

This method is deprecated. Use #identities instead.

Returns a collection that represents all of the verified email addresses for your account.

Returns:

  • (EmailAddressCollection) —

    Returns a collection that represents all of the verified email addresses for your account.



190
191
192
 
# File 'lib/aws/simple_email_service.rb', line 190

def email_addresses
  EmailAddressCollection.new(:config => config)
end

#identities ⇒ IdentityCollection

Returns:



195
196
197
 
# File 'lib/aws/simple_email_service.rb', line 195

def identities
  IdentityCollection.new(:config => config)
end

#quotas ⇒ Hash

Returns a hash of SES quotas and limits.

Examples:


ses.quotas
# {:max_24_hour_send=>200, :max_send_rate=>1.0, :sent_last_24_hours=>22}

Returns:

  • (Hash) —

    Returns a hash of SES quotas and limits.



360
361
362
 
# File 'lib/aws/simple_email_service.rb', line 360

def quotas
  Quotas.new(:config => config).to_h
end

#send_email(options = {}) ⇒ nil

Sends an email.

ses.send_email(
  :subject => 'A Sample Email',
  :to => '[email protected]', 
  :from => '[email protected]',
  :body_text => 'sample text ...',
  :body_html => '<p>sample text ...</p>')

You can also pass multiple email addresses for the :to, :cc, :bcc and :reply_to options. Email addresses can also be formatted with names.

ses.send_email(
  :subject => 'A Sample Email',
  :to => ['"John Doe" <[email protected]>', '"Jane Doe" <[email protected]>'],
  :from => '[email protected]',
  :body_text => 'sample text ...')

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :subject (required, String) —

    The subject of the message. A short summary of the content, which will appear in the # recipient’s inbox.

  • :from (required, String) —

    The sender’s email address.

  • :to (String, Array) —

    The address(es) to send the email to.

  • :cc (String, Array) —

    The address(es) to cc (carbon copy) the email to.

  • :bcc (String, Array) —

    The address(es) to bcc (blind carbon copy) the email to.

  • :reply_to (String, Array) —

    The reply-to email address(es) for the message. If the recipient replies to the message, each reply-to address will receive the reply.

  • :return_path (String) —

    The email address to which bounce notifications are to be forwarded. If the message cannot be delivered to the recipient, then an error message will be returned from the recipient’s ISP; this message will then be forwarded to the email address specified by the :return_path option.

  • :body_text (String) —

    The email text contents. You must provide :body_text, :body_html or both.

  • :body_html (String) —

    The email html contents. You must provide :body_text, :body_html or both.

  • :subject_charset (String) —

    The character set of the :subject string. If the text must contain any other characters, then you must also specify the character set. Examples include UTF-8, ISO-8859-1, and Shift_JIS. Defaults to 7-bit ASCII.

  • :body_text_charset (String) —

    The character set of the :body_text string. If the text must contain any other characters, then you must also specify the character set. Examples include UTF-8, ISO-8859-1, and Shift_JIS. Defaults to 7-bit ASCII.

  • :body_html_charset (String) —

    The character set of the :body_html string. If the text must contain any other characters, then you must also specify the character set. Examples include UTF-8, ISO-8859-1, and Shift_JIS. Defaults to 7-bit ASCII.

  • :body_html (String)

Returns:

  • (nil) 


254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/aws/simple_email_service.rb', line 254

def send_email options = {}

    require_each(options, :subject, :from)
    require_one_of(options, :to, :cc, :bcc)
    require_one_of(options, :body_text, :body_html)

  # these three options can be passed strings or arrays of strings,
  # but the service requires them in a list (array)
  [:to, :cc, :bcc, :reply_to].each do |key|
    if options[key]
      options[key] = [options[key]].flatten
    end
  end

  accepted_options = {
    :subject           => %w(message subject data),
    :subject_charset   => %w(message subject charset),
    :to                => %w(destination to_addresses),
    :cc                => %w(destination cc_addresses),
    :bcc               => %w(destination bcc_addresses),
    :from              => %w(source),
    :reply_to          => %w(reply_to_addresses),
    :return_path       => %w(return_path),
    :body_text         => %w(message body text data),
    :body_text_charset => %w(message body text charset),
    :body_html         => %w(message body html data),
    :body_html_charset => %w(message body html charset),
  }

  client.send_email(nest_options(options, accepted_options))
  nil

end

#send_raw_email(raw_message, options = {}) ⇒ nil Also known as: deliver, deliver!

Sends a raw email (email message, with header and content specified). Useful for sending multipart MIME emails. The raw text of the message must comply with Internet email standards; otherwise, the message cannot be sent.

raw = <<-EMAIL
Date: Wed, 1 Jun 2011 09:13:07 -0700
Subject: A Sample Email
From: "John Doe" <[email protected]>
To: "Jane Doe" <[email protected]>
Accept-Language: en-US
Content-Language: en-US
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: base64
MIME-Version: 1.0

c2FtcGxlIHRleHQNCg==
EMAIL

ses.send_raw_email(raw)

Amazon SES has a limit on the total number of recipients per message: The combined number of To:, CC: and BCC: email addresses cannot exceed 50. If you need to send an email message to a larger audience, you can divide your recipient list into groups of 50 or fewer, and then call Amazon SES repeatedly to send the message to each group.

Parameters:

  • raw_message (required, String) —

    The raw text of the message. You can pass in any object whos #to_s returns a valid formatted email (e.g. ruby Mail gem). The raw message should:

    • Contain a header and a body, separated by a blank line

    • Contain all required internet email headers

    • Each part of a multipart MIME message must be formatted properly

    • MIME content types must be among those supported by Amazon SES. Refer to the Amazon SES Developer Guide for more details.

    • Use content that is base64-encoded, if MIME requires it

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

    a customizable set of options

Options Hash (options):

  • :to (String, Array) —

    One or more email addresses to send the email to.

  • :from (String) —

    The sender’s email address.

    If you specify the :from option, then bounce notifications and complaints will be sent to this email address. This takes precedence over any Return-Path header that you might include in the raw_message.

Returns:

  • (nil) 


333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/aws/simple_email_service.rb', line 333

def send_raw_email raw_message, options = {}

  send_opts = {}
  send_opts[:raw_message] = {}
  send_opts[:raw_message][:data] = raw_message.to_s
  send_opts[:source] = options[:from] if options[:from]

  if raw_message.respond_to?(:destinations)
    send_opts[:destinations] = raw_message.destinations
  end
  send_opts[:destinations] = [options[:to]].flatten if options[:to]

  client.send_raw_email(send_opts)
  nil

end

#statistics ⇒ Array of Hashes

Returns an array of email statistics. Each object in this array is a hash with the following keys:

  • :delivery_attempts

  • :rejects

  • :bounces

  • :complaints

  • :timestamp

Returns:

  • (Array of Hashes) —

    An array of email statistic hashes.



374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/aws/simple_email_service.rb', line 374

def statistics
  response = client.get_send_statistics
  response.data[:send_data_points].collect do |data|
    {
      :sent => data[:timestamp],
      :delivery_attempts => data[:delivery_attempts],
      :rejects => data[:rejects],
      :bounces => data[:bounces],
      :complaints => data[:complaints],
    }
  end
end