aws-sdk 1.5.1 → 1.5.2

data/lib/aws/simple_email_service.rb

@@ -54,25 +54,60 @@ module AWS
   #
   # This has only been tested with Rails 2.3 and Rails 3.0.
   #
-  # = Email Addresses
   #
+  # = 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}[http://docs.amazonwebservices.com/ses/latest/DeveloperGuide/InitialSetup.Customer.html]
-  # you will only be able to send emails to and from verified email addresses.
-  # To verify an email address:
+  # you will only be able to send emails to and from verified email addresses 
+  # and domains.
   #
-  #   ses.email_addresses.verify('youremailaddress@domain.com')
+  # == Verifying Email Addresses
   #
-  # AWS will send an email to the given email address.  Follow the link in the
-  # email to verify the address.
+  # You can verify an email address for sending/receiving emails using
+  # the identities collection.
   #
-  # To explore the email addresses you have authorized:
+  #   identity = ses.identities.verify('email@yourdomain.com')
+  #   identity.verified? #=> false
   #
-  #   ses.email_addresses.each do |address|
-  #     puts address
-  #   end
+  # 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 identies:
   #
-  # See {EmailAddressCollection} for more information on working with SES email
-  # addresses.
+  #   ses.identites.map(&:identity)
+  #   #=> ['email@foo.com', '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 verfication status and token from identities as well.
+  #
+  #   # for an email address
+  #   identity = ses.identities['youremail@yourdomain.com']
+  #   identity.verified? #=> true/false
+  #
+  #   # for a domain
+  #   identity = ses.identities['yourdomain.com']
+  #   identity.verified? #=> true/false
+  #   identity.verification_token #=> '...'
   #
   # = Sending Email
   #
@@ -139,18 +174,26 @@ module AWS
       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(

data/lib/aws/simple_email_service/client.rb

@@ -28,6 +28,22 @@ module AWS
 
       ## client methods ##
 
+      # Calls the DeleteIdentity API operation.
+      # @method delete_identity(options = {})
+      #
+      # === Options:
+      #
+      # * +:identity+ - *required* - (String) The name of the identity to be
+      #   removed from the list of verified identities.
+      #
+      # === Response Structure:
+      #
+      # This method returns no response data.
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :delete_identity, 'DeleteIdentity'
+
       # Calls the DeleteVerifiedEmailAddress API operation.
       # @method delete_verified_email_address(options = {})
       #
@@ -44,6 +60,23 @@ module AWS
       #
       define_client_method :delete_verified_email_address, 'DeleteVerifiedEmailAddress'
 
+      # Calls the GetIdentityVerificationAttributes API operation.
+      # @method get_identity_verification_attributes(options = {})
+      #
+      # === Options:
+      #
+      # * +:identities+ - *required* - (Array<String>)
+      #
+      # === Response Structure:
+      #
+      # * +:verification_attributes+ - (Hash<String,Hash>)
+      #   * +:verification_status+ - (String)
+      #   * +:verification_token+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :get_identity_verification_attributes, 'GetIdentityVerificationAttributes'
+
       # Calls the GetSendQuota API operation.
       # @method get_send_quota(options = {})
       #
@@ -81,6 +114,26 @@ module AWS
       #
       define_client_method :get_send_statistics, 'GetSendStatistics'
 
+      # Calls the ListIdentities API operation.
+      # @method list_identities(options = {})
+      #
+      # === Options:
+      #
+      # * +:identity_type+ - (String) The type of the identities listed.
+      #   Possible values are: "EmailAddress", "Domain" or null.
+      # * +:next_token+ - (String) The token used for retrieving the next set
+      #   of items.
+      # * +:max_items+ - (Integer) The maximum number of items returned.
+      #
+      # === Response Structure:
+      #
+      # * +:identities+ - (Array<String>)
+      # * +:next_token+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :list_identities, 'ListIdentities'
+
       # Calls the ListVerifiedEmailAddresses API operation.
       # @method list_verified_email_addresses(options = {})
       #
@@ -101,7 +154,7 @@ module AWS
       #
       # === Options:
       #
-      # * +:source+ - *required* - (String) The sender's email address.
+      # * +:source+ - *required* - (String) The identity's email address.
       # * +:destination+ - *required* - (Hash) The destination for this email,
       #   composed of To:, CC:, and BCC: fields.
       #   * +:to_addresses+ - (Array<String>) The To: field(s) of the message.
@@ -150,7 +203,7 @@ module AWS
       #
       # === Options:
       #
-      # * +:source+ - (String) The sender's email address. If you specify the
+      # * +:source+ - (String) The identity's email address. If you specify the
       #   Source parameter, 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 text of the
@@ -168,7 +221,7 @@ module AWS
       #     client must ensure that the message format complies with Internet
       #     email standards regarding email header fields, MIME types, MIME
       #     encoding, and base64 encoding (if necessary). For more information,
-      #     go to the Amazon SES Developer Guide.
+      #     go to theAmazon SES Developer Guide.
       #
       # === Response Structure:
       #
@@ -178,6 +231,22 @@ module AWS
       #
       define_client_method :send_raw_email, 'SendRawEmail'
 
+      # Calls the VerifyDomainIdentity API operation.
+      # @method verify_domain_identity(options = {})
+      #
+      # === Options:
+      #
+      # * +:domain+ - *required* - (String) The name of the domain to be
+      #   verified.
+      #
+      # === Response Structure:
+      #
+      # * +:verification_token+ - (String)
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :verify_domain_identity, 'VerifyDomainIdentity'
+
       # Calls the VerifyEmailAddress API operation.
       # @method verify_email_address(options = {})
       #
@@ -194,6 +263,22 @@ module AWS
       #
       define_client_method :verify_email_address, 'VerifyEmailAddress'
 
+      # Calls the VerifyEmailIdentity API operation.
+      # @method verify_email_identity(options = {})
+      #
+      # === Options:
+      #
+      # * +:email_address+ - *required* - (String) The email address to be
+      #   verified.
+      #
+      # === Response Structure:
+      #
+      # This method returns no response data.
+      #
+      # @return [Core::Response]
+      #
+      define_client_method :verify_email_identity, 'VerifyEmailIdentity'
+
       ## end client methods ##
 
     end

data/lib/aws/simple_email_service/email_address_collection.rb

@@ -15,6 +15,8 @@ module AWS
   class SimpleEmailService
 
     # Helps you manage your verified SimpleEmailService email addresses.
+    # @note This class is deprecated. Please use 
+    #   {SimpleEmailService#identities} instead.
     class EmailAddressCollection
 
       include Core::Model
@@ -26,6 +28,7 @@ module AWS
       #
       # @param [String] email_address The email address to verify.
       # @return [nil]
+      # @note This method is deprecated.
       def verify email_address
         client.verify_email_address(:email_address => email_address)
         nil
@@ -36,11 +39,13 @@ module AWS
       #   of verified email addresses.  Useful for cleanup as there is a 100
       #   email address limit.
       # @return [nil]
+      # @note This method is deprecated.
       def delete email_address
         client.delete_verified_email_address(:email_address => email_address)
         nil
       end
 
+      # @note This method is deprecated.
       def include?
         # this is so jruby can detect that verified? is an alias
         super
@@ -50,6 +55,7 @@ module AWS
       # Yields each verified email address as a string.
       # @return [nil]
       #   yielded.
+      # @note This method is deprecated.
       def each &block
         response = client.list_verified_email_addresses({})
         response.verified_email_addresses.each do |email_address|

data/lib/aws/simple_email_service/identity.rb

@@ -0,0 +1,91 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  class SimpleEmailService
+
+    # @attr_reader [String] verification_status
+    #
+    # @attr_reader [String,nil] verification_token
+    #
+    class Identity < Core::Resource
+
+      # @private
+      def initialize email_address_or_domain, options = {}
+        @identity = email_address_or_domain
+        super
+      end
+
+      # @return [String] Returns the email address or domain name for
+      #   this identity.
+      attr_reader :identity
+
+      attribute :verification_status
+
+      attribute :verification_token, :static => true
+
+      populates_from(:get_identity_verification_attributes) do |resp|
+        resp.data[:verification_attributes][identity]
+      end
+
+      # @return [Boolean] Returns +true+ if this {Identity} represents an
+      #   email address.
+      def email_address?
+        identity =~ /@/ ? true : false
+      end
+
+      # @return [Boolean] Returns +true+ if this {Identity} represents a
+      #   domain.
+      def domain?
+        !email_address?
+      end
+
+      # @return [Boolean] Returns +true+ if this email address/domain has
+      #   been verified.
+      def verified?
+        verification_status == 'Success'
+      end
+
+      # @return [Boolean] Returns +true+ if verification for this email 
+      #   address/domain is still pending.
+      def pending?
+        verification_status == 'Pending'
+      end
+
+      # Deletes the current identity.
+      # @return [nil]
+      def delete
+        client.delete_identity(:identity => identity)  
+        nil
+      end
+
+      # @return [Boolean] Returns true if the identity exists.
+      def exists?
+        !!get_resource[:verification_attributes][identity]
+      end
+
+      protected
+
+      def resource_identifiers
+        [[:identity, identity]]
+      end
+
+      def get_resource attr = nil
+        client_opts = {}
+        client_opts[:identities] = [identity]
+        client.get_identity_verification_attributes(client_opts)
+      end
+
+    end
+  end
+end

data/lib/aws/simple_email_service/identity_collection.rb

@@ -0,0 +1,81 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  class SimpleEmailService
+    class IdentityCollection
+
+      include Core::Collection::Limitable
+
+      # @private
+      def initialize options = {}
+        @type = options[:type]
+        super
+      end
+
+      # Request verification for an email address or a domain.
+      # @param [String] email_or_domain
+      # @return [Identity] Returns an {Iidentity} object.  Identities for 
+      #   domains will have a #verification_token.
+      def verify email_or_domain
+
+        resp = email_or_domain =~ /@/ ?
+          client.verify_email_identity(:email_address => email_or_domain) :
+          client.verify_domain_identity(:domain => email_or_domain)
+
+        Identity.new(email_or_domain, 
+          :verification_token => resp.data[:verification_token],
+          :config => config)
+
+      end
+      alias_method :create, :verify
+
+      # @param [String] email_or_domain
+      # @return [Identity] Returns an {Identity} with the given
+      #   email address or domain name.
+      def [] email_or_domain
+        Identity.new(email_or_domain, :config => config)
+      end
+
+      # @return [IdentityCollection] Returns a collection that only
+      #   enumerates email addresses.
+      def email_addresses
+        self.class.new(:type => 'EmailAddress', :config => config)
+      end
+
+      # @return [IdentityCollection] Returns a collection that only
+      #   enumerates domains.
+      def domains
+        self.class.new(:type => 'Domain', :config => config)
+      end
+
+      protected
+
+      def _each_item next_token, limit, options = {}, &block
+
+        options[:max_items] = limit if limit
+        options[:next_token] = next_token if next_token
+        options[:identity_type] = @type if @type
+
+        resp = client.list_identities(options)
+        resp.data[:identities].each do |identity|
+          yield(self[identity])
+        end
+
+        resp.data[:next_token]
+
+      end
+
+    end
+  end
+end