postmark 1.14.0 → 1.15.0

data/VERSION

@@ -1 +1 @@
-1.14.0
+1.15.0

data/lib/postmark/api_client.rb

@@ -27,6 +27,11 @@ module Postmark
     end
 
     def deliver_message(message)
+      if message.templated?
+        raise ArgumentError,
+              "Please use #{self.class}#deliver_message_with_template to deliver messages with templates."
+      end
+
       data = serialize(message.to_postmark_hash)
 
       with_retries do
@@ -37,7 +42,26 @@ module Postmark
       end
     end
 
+    def deliver_message_with_template(message)
+      raise ArgumentError, 'Templated delivery requested, but the template is missing.' unless message.templated?
+
+      data = serialize(message.to_postmark_hash)
+
+      with_retries do
+        response, error = take_response_of { http_client.post("email/withTemplate", data) }
+        update_message(message, response)
+        raise error if error
+        format_response(response, true)
+      end
+    end
+
     def deliver_messages(messages)
+      if messages.any? { |m| m.templated? }
+        raise ArgumentError,
+              "Some of the provided messages have templates. Please use " \
+              "#{self.class}#deliver_messages_with_templates to deliver those."
+      end
+
       in_batches(messages) do |batch, offset|
         data = serialize(batch.map { |m| m.to_postmark_hash })
 
@@ -51,6 +75,24 @@ module Postmark
       end
     end
 
+    def deliver_messages_with_templates(messages)
+      unless messages.all? { |m| m.templated? }
+        raise ArgumentError, 'Templated delivery requested, but one or more messages lack templates.'
+      end
+
+      in_batches(messages) do |batch, offset|
+        data = serialize(batch.map { |m| m.to_postmark_hash })
+
+        with_retries do
+          http_client.post("email/batchWithTemplates", data).tap do |response|
+            response.each_with_index do |r, i|
+              update_message(messages[offset + i], r)
+            end
+          end
+        end
+      end
+    end
+
     def delivery_stats
       response = format_response(http_client.get("deliverystats"), true)
 

data/lib/postmark/error.rb

@@ -99,12 +99,22 @@ module Postmark
     end
   end
 
+  class InvalidTemplateError < Error
+    attr_reader :postmark_response
+
+    def initialize(response)
+      @postmark_response = response
+      super('Failed to render the template. Please check #postmark_response on this error for details.')
+    end
+  end
+
   class TimeoutError < Error
     def retry?
       true
     end
   end
 
+  class MailAdapterError < Postmark::Error; end
   class UnknownMessageType < Error; end
   class InvalidApiKeyError < HttpServerError; end
   class InternalServerError < HttpServerError; end

data/lib/postmark/handlers/mail.rb

@@ -8,10 +8,11 @@ module Mail
     end
 
     def deliver!(mail)
-      settings = self.settings.dup
-      api_token = settings.delete(:api_token) || settings.delete(:api_key)
-      api_client = ::Postmark::ApiClient.new(api_token, settings)
-      response = api_client.deliver_message(mail)
+      response = if mail.templated?
+                   api_client.deliver_message_with_template(mail)
+                 else
+                   api_client.deliver_message(mail)
+                 end
 
       if settings[:return_response]
         response
@@ -20,5 +21,10 @@ module Mail
       end
     end
 
+    def api_client
+      settings = self.settings.dup
+      api_token = settings.delete(:api_token) || settings.delete(:api_key)
+      ::Postmark::ApiClient.new(api_token, settings)
+    end
   end
 end

data/lib/postmark/mail_message_converter.rb

@@ -7,10 +7,10 @@ module Postmark
     end
 
     def run
-      delete_blank_fields(convert)
+      delete_blank_fields(pick_fields(convert, @message.templated?))
     end
 
-    protected
+    private
 
     def convert
       headers_part.merge(content_part)
@@ -32,10 +32,22 @@ module Postmark
         'Tag' => @message.tag.to_s,
         'TrackOpens' => (cast_to_bool(@message.track_opens) unless @message.track_opens.empty?),
         'TrackLinks' => (::Postmark::Inflector.to_postmark(@message.track_links) unless @message.track_links.empty?),
-        'Metadata' => @message.metadata
+        'Metadata' => @message.metadata,
+        'TemplateAlias' => @message.template_alias,
+        'TemplateModel' => @message.template_model
       }
     end
 
+    def pick_fields(message_hash, templated = false)
+      fields = if templated
+                 %w(Subject HtmlBody TextBody)
+               else
+                 %w(TemplateAlias TemplateModel)
+               end
+      fields.each { |key| message_hash.delete(key) }
+      message_hash
+    end
+
     def content_part
       {
         'Attachments' => @message.export_attachments,
@@ -44,8 +56,6 @@ module Postmark
       }
     end
 
-    protected
-
     def cast_to_bool(val)
       if val.is_a?(TrueClass) || val.is_a?(FalseClass)
         val

data/lib/postmark/message_extensions/mail.rb

@@ -61,6 +61,50 @@ module Mail
       ::Postmark::MessageHelper.attachments_to_postmark(@_attachments)
     end
 
+    def template_alias(val = nil)
+      return self[:postmark_template_alias] && self[:postmark_template_alias].to_s if val.nil?
+      self[:postmark_template_alias] = val
+    end
+
+    attr_writer :template_model
+    def template_model(model = nil)
+      return @template_model if model.nil?
+      @template_model = model
+    end
+
+    def templated?
+      !!template_alias
+    end
+
+    def prerender
+      raise ::Postmark::Error, 'Cannot prerender a message without an associated template alias' unless templated?
+
+      unless delivery_method.is_a?(::Mail::Postmark)
+        raise ::Postmark::MailAdapterError, "Cannot render templates via #{delivery_method.class} adapter."
+      end
+
+      client = delivery_method.api_client
+      template = client.get_template(template_alias)
+      response = client.validate_template(template.merge(:test_render_model => template_model || {}))
+
+      raise ::Postmark::InvalidTemplateError, response unless response[:all_content_is_valid]
+
+      self.body = nil
+
+      subject response[:subject][:rendered_content]
+
+      text_part do
+        body response[:text_body][:rendered_content]
+      end
+
+      html_part do
+        content_type 'text/html; charset=UTF-8'
+        body response[:html_body][:rendered_content]
+      end
+
+      self
+    end
+
     def text?
       if defined?(super)
         super
@@ -139,6 +183,7 @@ module Mail
         subject      tag
         attachment   to
         track-opens  track-links
+        postmark-template-alias
       ]
     end
 

data/lib/postmark/version.rb

@@ -1,3 +1,3 @@
 module Postmark
-  VERSION = '1.14.0'
+  VERSION = '1.15.0'
 end

data/postmark.gemspec

@@ -33,8 +33,8 @@ Gem::Specification.new do |s|
 
   s.required_rubygems_version = ">= 1.3.7"
 
-  s.add_dependency "rake"
   s.add_dependency "json"
 
   s.add_development_dependency "mail"
+  s.add_development_dependency "rake"
 end

data/spec/support/custom_matchers.rb

@@ -28,3 +28,7 @@ RSpec::Matchers.define :a_postmark_json do |string|
     postmark_json?(actual)
   end
 end
+
+RSpec::Matchers.define :json_representation_of do |x|
+  match { |actual| Postmark::Json.decode(actual) == x }
+end

data/spec/unit/postmark/api_client_spec.rb

@@ -10,6 +10,14 @@ describe Postmark::ApiClient do
       delivery_method Mail::Postmark
     end
   }
+  let(:templated_message) do
+    Mail.new do
+      from            "sheldon@bigbangtheory.com"
+      to              "lenard@bigbangtheory.com"
+      template_alias  "hello"
+      template_model  :name => "Sheldon"
+    end
+  end
 
   let(:api_client) {Postmark::ApiClient.new(api_token)}
   subject {api_client}
@@ -95,6 +103,11 @@ describe Postmark::ApiClient do
     let(:email_json) {Postmark::Json.encode(email)}
     let(:http_client) {subject.http_client}
 
+    it 'raises an error when given a templated message' do
+      expect { subject.deliver_message(templated_message) }.
+        to raise_error(ArgumentError, /Please use Postmark::ApiClient\#deliver_message_with_template/)
+    end
+
     it 'turns message into a JSON document and posts it to /email' do
       expect(http_client).to receive(:post).with('email', email_json)
       subject.deliver_message(message)
@@ -118,7 +131,41 @@ describe Postmark::ApiClient do
       allow(http_client).to receive(:post).and_raise(Postmark::TimeoutError)
       expect {subject.deliver_message(message)}.to raise_error(Postmark::TimeoutError)
     end
+  end
 
+  describe "#deliver_message_with_template" do
+    let(:email) {templated_message.to_postmark_hash}
+    let(:email_json) {Postmark::Json.encode(email)}
+    let(:http_client) {subject.http_client}
+
+    it 'raises an error when given a non-templated message' do
+      expect { subject.deliver_message_with_template(message) }.
+        to raise_error(ArgumentError, 'Templated delivery requested, but the template is missing.')
+    end
+
+    it 'turns message into a JSON document and posts it to /email' do
+      expect(http_client).to receive(:post).with('email/withTemplate', email_json)
+      subject.deliver_message_with_template(templated_message)
+    end
+
+    it "retries 3 times" do
+      2.times do
+        expect(http_client).to receive(:post).and_raise(Postmark::InternalServerError)
+      end
+      expect(http_client).to receive(:post)
+      expect {subject.deliver_message_with_template(templated_message)}.not_to raise_error
+    end
+
+    it "retries on timeout" do
+      expect(http_client).to receive(:post).and_raise(Postmark::TimeoutError)
+      expect(http_client).to receive(:post)
+      expect {subject.deliver_message_with_template(templated_message)}.not_to raise_error
+    end
+
+    it "proxies errors" do
+      allow(http_client).to receive(:post).and_raise(Postmark::TimeoutError)
+      expect {subject.deliver_message_with_template(templated_message)}.to raise_error(Postmark::TimeoutError)
+    end
   end
 
   describe "#deliver_messages" do
@@ -128,6 +175,11 @@ describe Postmark::ApiClient do
     let(:http_client) {subject.http_client}
     let(:response) {[{}, {}, {}]}
 
+    it 'raises an error when given a templated message' do
+      expect { subject.deliver_messages([templated_message]) }.
+        to raise_error(ArgumentError, /Please use Postmark::ApiClient\#deliver_messages_with_templates/)
+    end
+
     it 'turns array of messages into a JSON document and posts it to /email/batch' do
       expect(http_client).to receive(:post).with('email/batch', emails_json) {response}
       subject.deliver_messages([message, message, message])
@@ -146,7 +198,39 @@ describe Postmark::ApiClient do
       expect(http_client).to receive(:post) {response}
       expect {subject.deliver_messages([message, message, message])}.not_to raise_error
     end
+  end
+
+  describe "#deliver_messages_with_templates" do
+    let(:email) {templated_message.to_postmark_hash}
+    let(:emails) {[email, email, email]}
+    let(:emails_json) {Postmark::Json.encode(emails)}
+    let(:http_client) {subject.http_client}
+    let(:response) {[{}, {}, {}]}
+    let(:messages) { Array.new(3) { templated_message } }
 
+    it 'raises an error when given a templated message' do
+      expect { subject.deliver_messages_with_templates([message]) }.
+        to raise_error(ArgumentError, 'Templated delivery requested, but one or more messages lack templates.')
+    end
+
+    it 'turns array of messages into a JSON document and posts it to /email/batch' do
+      expect(http_client).to receive(:post).with('email/batchWithTemplates', emails_json) {response}
+      subject.deliver_messages_with_templates(messages)
+    end
+
+    it "should retry 3 times" do
+      2.times do
+        expect(http_client).to receive(:post).and_raise(Postmark::InternalServerError)
+      end
+      expect(http_client).to receive(:post) {response}
+      expect {subject.deliver_messages_with_templates(messages)}.not_to raise_error
+    end
+
+    it "should retry on timeout" do
+      expect(http_client).to receive(:post).and_raise(Postmark::TimeoutError)
+      expect(http_client).to receive(:post) {response}
+      expect {subject.deliver_messages_with_templates(messages)}.not_to raise_error
+    end
   end
 
   describe "#delivery_stats" do
@@ -716,9 +800,9 @@ describe Postmark::ApiClient do
     end
 
     it 'performs a POST request to /templates with the given attributes' do
-      expected_json = {'Name' => 'template name'}.to_json
-
-      expect(http_client).to receive(:post).with('templates', expected_json).and_return(response)
+      expect(http_client).to receive(:post).
+        with('templates', json_representation_of('Name' => 'template name')).
+        and_return(response)
 
       template = subject.create_template(:name => 'template name')
 
@@ -738,9 +822,9 @@ describe Postmark::ApiClient do
     end
 
     it 'performs a PUT request to /templates with the given attributes' do
-      expected_json = {'Name' => 'template name'}.to_json
-
-      expect(http_client).to receive(:put).with('templates/123', expected_json).and_return(response)
+      expect(http_client).to receive(:put).
+        with('templates/123', json_representation_of('Name' => 'template name')).
+        and_return(response)
 
       template = subject.update_template(123, :name => 'template name')
 
@@ -796,13 +880,12 @@ describe Postmark::ApiClient do
       end
 
       it 'performs a POST request and returns unmodified suggested template model' do
-        expected_template_json = {
-            'HtmlBody' => '{{MyName}}',
-            'TextBody' => '{{MyName}}',
-            'Subject' => '{{MyName}}'
-        }.to_json
-
-        expect(http_client).to receive(:post).with('templates/validate', expected_template_json).and_return(response)
+        expect(http_client).to receive(:post).
+          with('templates/validate',
+               json_representation_of('HtmlBody' => '{{MyName}}',
+                                      'TextBody' => '{{MyName}}',
+                                      'Subject' => '{{MyName}}')).
+          and_return(response)
 
         resp = subject.validate_template(:html_body => '{{MyName}}',
                                          :text_body => '{{MyName}}',
@@ -845,13 +928,11 @@ describe Postmark::ApiClient do
       end
 
       it 'performs a POST request and returns validation errors' do
-        expected_template_json = {
-            'HtmlBody' => '{{#each}}',
-            'TextBody' => '{{MyName}}',
-            'Subject' => '{{MyName}}'
-        }.to_json
-
-        expect(http_client).to receive(:post).with('templates/validate', expected_template_json).and_return(response)
+        expect(http_client).
+          to receive(:post).with('templates/validate',
+                                 json_representation_of('HtmlBody' => '{{#each}}',
+                                                        'TextBody' => '{{MyName}}',
+                                                        'Subject' => '{{MyName}}')).and_return(response)
 
         resp = subject.validate_template(:html_body => '{{#each}}',
                                          :text_body => '{{MyName}}',
@@ -868,12 +949,11 @@ describe Postmark::ApiClient do
 
   describe "#deliver_with_template" do
     let(:email) {Postmark::MessageHelper.to_postmark(message_hash)}
-    let(:email_json) {Postmark::Json.encode(email)}
     let(:http_client) {subject.http_client}
     let(:response) {{"MessageID" => 42}}
 
     it 'converts message hash to Postmark format and posts it to /email/withTemplate' do
-      expect(http_client).to receive(:post).with('email/withTemplate', email_json) {response}
+      expect(http_client).to receive(:post).with('email/withTemplate', json_representation_of(email)) {response}
       subject.deliver_with_template(message_hash)
     end
 
@@ -886,7 +966,7 @@ describe Postmark::ApiClient do
     end
 
     it 'converts response to ruby format' do
-      expect(http_client).to receive(:post).with('email/withTemplate', email_json) {response}
+      expect(http_client).to receive(:post).with('email/withTemplate', json_representation_of(email)) {response}
       r = subject.deliver_with_template(message_hash)
       r.should have_key(:message_id)
     end