postmark_ruby_client 0.1.0

data/lib/postmark_client/models/attachment.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module PostmarkClient
+  # Represents an email attachment for the Postmark API.
+  #
+  # @example Creating a simple attachment
+  #   attachment = PostmarkClient::Attachment.new(
+  #     name: "document.pdf",
+  #     content: File.read("document.pdf"),
+  #     content_type: "application/pdf"
+  #   )
+  #
+  # @example Creating an inline image attachment
+  #   attachment = PostmarkClient::Attachment.new(
+  #     name: "logo.png",
+  #     content: File.read("logo.png"),
+  #     content_type: "image/png",
+  #     content_id: "cid:logo.png"
+  #   )
+  #
+  # @example Creating from a file path
+  #   attachment = PostmarkClient::Attachment.from_file("path/to/file.pdf")
+  class Attachment
+    # @return [String] the filename of the attachment
+    attr_accessor :name
+
+    # @return [String] the Base64-encoded content of the attachment
+    attr_accessor :content
+
+    # @return [String] the MIME type of the attachment
+    attr_accessor :content_type
+
+    # @return [String, nil] the content ID for inline attachments
+    attr_accessor :content_id
+
+    # Initialize a new attachment
+    #
+    # @param name [String] the filename
+    # @param content [String] the file content (will be Base64 encoded if not already)
+    # @param content_type [String] the MIME type
+    # @param content_id [String, nil] optional content ID for inline images
+    # @param base64_encoded [Boolean] whether content is already Base64 encoded
+    def initialize(name:, content:, content_type:, content_id: nil, base64_encoded: false)
+      @name = name
+      @content = base64_encoded ? content : Base64.strict_encode64(content)
+      @content_type = content_type
+      @content_id = content_id
+    end
+
+    # Create an attachment from a file path
+    #
+    # @param file_path [String] path to the file
+    # @param content_type [String, nil] optional MIME type (auto-detected if not provided)
+    # @param content_id [String, nil] optional content ID for inline images
+    # @return [Attachment] a new attachment instance
+    def self.from_file(file_path, content_type: nil, content_id: nil)
+      name = File.basename(file_path)
+      content = File.binread(file_path)
+      detected_content_type = content_type || detect_content_type(name)
+
+      new(
+        name: name,
+        content: content,
+        content_type: detected_content_type,
+        content_id: content_id
+      )
+    end
+
+    # Convert the attachment to a hash for API requests
+    #
+    # @return [Hash] the attachment as a hash
+    def to_h
+      hash = {
+        "Name" => name,
+        "Content" => content,
+        "ContentType" => content_type
+      }
+      hash["ContentID"] = content_id if content_id
+      hash
+    end
+
+    # Check if this is an inline attachment
+    #
+    # @return [Boolean] true if this is an inline attachment
+    def inline?
+      !content_id.nil?
+    end
+
+    private
+
+    # Detect content type from file extension
+    #
+    # @param filename [String] the filename
+    # @return [String] the detected MIME type
+    def self.detect_content_type(filename)
+      extension = File.extname(filename).downcase.delete(".")
+
+      CONTENT_TYPES.fetch(extension, "application/octet-stream")
+    end
+
+    # Common content types by file extension
+    CONTENT_TYPES = {
+      "pdf" => "application/pdf",
+      "doc" => "application/msword",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "xls" => "application/vnd.ms-excel",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "png" => "image/png",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "gif" => "image/gif",
+      "svg" => "image/svg+xml",
+      "txt" => "text/plain",
+      "html" => "text/html",
+      "htm" => "text/html",
+      "css" => "text/css",
+      "js" => "application/javascript",
+      "json" => "application/json",
+      "xml" => "application/xml",
+      "zip" => "application/zip",
+      "csv" => "text/csv"
+    }.freeze
+  end
+end

data/lib/postmark_client/models/email.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module PostmarkClient
+  # Represents an email message for the Postmark API.
+  # Provides a clean Ruby interface for building email payloads.
+  #
+  # @example Creating a simple email
+  #   email = PostmarkClient::Email.new(
+  #     from: "sender@example.com",
+  #     to: "recipient@example.com",
+  #     subject: "Hello!",
+  #     text_body: "Hello, World!"
+  #   )
+  #
+  # @example Creating an email with HTML and attachments
+  #   email = PostmarkClient::Email.new(
+  #     from: "John Doe <john@example.com>",
+  #     to: ["alice@example.com", "bob@example.com"],
+  #     cc: "manager@example.com",
+  #     subject: "Monthly Report",
+  #     html_body: "<h1>Report</h1><p>See attached.</p>",
+  #     text_body: "Report - See attached.",
+  #     track_opens: true
+  #   )
+  #   email.add_attachment(name: "report.pdf", content: pdf_data, content_type: "application/pdf")
+  #
+  # @example Using the builder pattern
+  #   email = PostmarkClient::Email.new
+  #     .from("sender@example.com")
+  #     .to("recipient@example.com")
+  #     .subject("Hello")
+  #     .text_body("Hello, World!")
+  class Email
+    # @return [String] sender email address
+    attr_accessor :from
+
+    # @return [String, Array<String>] recipient email address(es)
+    attr_accessor :to
+
+    # @return [String, Array<String>, nil] CC recipient email address(es)
+    attr_accessor :cc
+
+    # @return [String, Array<String>, nil] BCC recipient email address(es)
+    attr_accessor :bcc
+
+    # @return [String] email subject
+    attr_accessor :subject
+
+    # @return [String, nil] HTML email body
+    attr_accessor :html_body
+
+    # @return [String, nil] plain text email body
+    attr_accessor :text_body
+
+    # @return [String, nil] reply-to email address
+    attr_accessor :reply_to
+
+    # @return [String, nil] email tag for categorization
+    attr_accessor :tag
+
+    # @return [Array<Hash>] custom email headers
+    attr_accessor :headers
+
+    # @return [Boolean] whether to track email opens
+    attr_accessor :track_opens
+
+    # @return [String] link tracking setting ("None", "HtmlAndText", "HtmlOnly", "TextOnly")
+    attr_accessor :track_links
+
+    # @return [Array<Attachment>] email attachments
+    attr_accessor :attachments
+
+    # @return [Hash] custom metadata key-value pairs
+    attr_accessor :metadata
+
+    # @return [String] message stream identifier
+    attr_accessor :message_stream
+
+    # Valid link tracking options
+    TRACK_LINKS_OPTIONS = %w[None HtmlAndText HtmlOnly TextOnly].freeze
+
+    # Initialize a new email
+    #
+    # @param from [String, nil] sender email address
+    # @param to [String, Array<String>, nil] recipient email address(es)
+    # @param cc [String, Array<String>, nil] CC recipient(s)
+    # @param bcc [String, Array<String>, nil] BCC recipient(s)
+    # @param subject [String, nil] email subject
+    # @param html_body [String, nil] HTML body
+    # @param text_body [String, nil] plain text body
+    # @param reply_to [String, nil] reply-to address
+    # @param tag [String, nil] email tag
+    # @param headers [Array<Hash>, nil] custom headers
+    # @param track_opens [Boolean, nil] track opens
+    # @param track_links [String, nil] link tracking setting
+    # @param attachments [Array<Attachment>, nil] attachments
+    # @param metadata [Hash, nil] custom metadata
+    # @param message_stream [String, nil] message stream
+    def initialize(
+      from: nil,
+      to: nil,
+      cc: nil,
+      bcc: nil,
+      subject: nil,
+      html_body: nil,
+      text_body: nil,
+      reply_to: nil,
+      tag: nil,
+      headers: nil,
+      track_opens: nil,
+      track_links: nil,
+      attachments: nil,
+      metadata: nil,
+      message_stream: nil
+    )
+      @from = from
+      @to = to
+      @cc = cc
+      @bcc = bcc
+      @subject = subject
+      @html_body = html_body
+      @text_body = text_body
+      @reply_to = reply_to
+      @tag = tag
+      @headers = headers || []
+      @track_opens = track_opens
+      @track_links = track_links
+      @attachments = attachments || []
+      @metadata = metadata || {}
+      @message_stream = message_stream || PostmarkClient.configuration.default_message_stream
+    end
+
+    # Add a custom header to the email
+    #
+    # @param name [String] header name
+    # @param value [String] header value
+    # @return [self] returns self for method chaining
+    def add_header(name:, value:)
+      @headers << { "Name" => name, "Value" => value }
+      self
+    end
+
+    # Add an attachment to the email
+    #
+    # @param attachment [Attachment] an Attachment instance
+    # @return [self] returns self for method chaining
+    #
+    # @overload add_attachment(attachment)
+    #   @param attachment [Attachment] an Attachment instance
+    #
+    # @overload add_attachment(name:, content:, content_type:, content_id: nil)
+    #   @param name [String] filename
+    #   @param content [String] file content
+    #   @param content_type [String] MIME type
+    #   @param content_id [String, nil] content ID for inline attachments
+    def add_attachment(attachment = nil, **kwargs)
+      if attachment.is_a?(Attachment)
+        @attachments << attachment
+      elsif kwargs.any?
+        @attachments << Attachment.new(**kwargs)
+      else
+        raise ArgumentError, "Must provide an Attachment instance or attachment parameters"
+      end
+      self
+    end
+
+    # Add a file as an attachment
+    #
+    # @param file_path [String] path to the file
+    # @param content_type [String, nil] optional MIME type
+    # @param content_id [String, nil] optional content ID
+    # @return [self] returns self for method chaining
+    def attach_file(file_path, content_type: nil, content_id: nil)
+      @attachments << Attachment.from_file(file_path, content_type: content_type, content_id: content_id)
+      self
+    end
+
+    # Add metadata to the email
+    #
+    # @param key [String, Symbol] metadata key
+    # @param value [String] metadata value
+    # @return [self] returns self for method chaining
+    def add_metadata(key, value)
+      @metadata[key.to_s] = value
+      self
+    end
+
+    # Validate the email before sending
+    #
+    # @return [Boolean] true if valid
+    # @raise [ValidationError] if validation fails
+    def validate!
+      raise ValidationError, "From address is required" if from.nil? || from.empty?
+      raise ValidationError, "To address is required" if to.nil? || (to.is_a?(Array) && to.empty?) || (to.is_a?(String) && to.empty?)
+      raise ValidationError, "Either HtmlBody or TextBody is required" if (html_body.nil? || html_body.empty?) && (text_body.nil? || text_body.empty?)
+
+      if track_links && !TRACK_LINKS_OPTIONS.include?(track_links)
+        raise ValidationError, "TrackLinks must be one of: #{TRACK_LINKS_OPTIONS.join(', ')}"
+      end
+
+      true
+    end
+
+    # Check if the email is valid
+    #
+    # @return [Boolean] true if valid, false otherwise
+    def valid?
+      validate!
+      true
+    rescue ValidationError
+      false
+    end
+
+    # Convert the email to a hash for API requests
+    #
+    # @return [Hash] the email as a hash matching Postmark API format
+    def to_h
+      hash = {}
+
+      hash["From"] = from if from
+      hash["To"] = normalize_recipients(to) if to
+      hash["Cc"] = normalize_recipients(cc) if cc
+      hash["Bcc"] = normalize_recipients(bcc) if bcc
+      hash["Subject"] = subject if subject
+      hash["HtmlBody"] = html_body if html_body
+      hash["TextBody"] = text_body if text_body
+      hash["ReplyTo"] = reply_to if reply_to
+      hash["Tag"] = tag if tag
+      hash["Headers"] = headers if headers.any?
+      hash["TrackOpens"] = track_opens unless track_opens.nil?
+      hash["TrackLinks"] = track_links if track_links
+      hash["Attachments"] = attachments.map(&:to_h) if attachments.any?
+      hash["Metadata"] = metadata if metadata.any?
+      hash["MessageStream"] = message_stream if message_stream
+
+      hash
+    end
+
+    # Alias for to_h
+    alias_method :to_api_hash, :to_h
+
+    private
+
+    # Normalize recipients to comma-separated string
+    #
+    # @param recipients [String, Array<String>] recipient(s)
+    # @return [String] comma-separated recipients
+    def normalize_recipients(recipients)
+      return recipients if recipients.is_a?(String)
+
+      recipients.join(", ")
+    end
+  end
+end

data/lib/postmark_client/models/email_response.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module PostmarkClient
+  # Represents a response from the Postmark Email API.
+  # Wraps the API response in a convenient Ruby object.
+  #
+  # @example Handling a successful response
+  #   response = client.send_email(email)
+  #   puts "Message ID: #{response.message_id}"
+  #   puts "Submitted at: #{response.submitted_at}"
+  #
+  # @example Checking for errors
+  #   if response.success?
+  #     puts "Email sent successfully!"
+  #   else
+  #     puts "Error: #{response.message}"
+  #   end
+  class EmailResponse
+    # @return [String] recipient email address
+    attr_reader :to
+
+    # @return [Time] timestamp when the email was submitted
+    attr_reader :submitted_at
+
+    # @return [String] unique message identifier
+    attr_reader :message_id
+
+    # @return [Integer] error code (0 means success)
+    attr_reader :error_code
+
+    # @return [String] response message
+    attr_reader :message
+
+    # @return [Hash] raw response data
+    attr_reader :raw_response
+
+    # Initialize from API response hash
+    #
+    # @param response [Hash] the API response
+    def initialize(response)
+      @raw_response = response
+      @to = response["To"]
+      @submitted_at = parse_timestamp(response["SubmittedAt"])
+      @message_id = response["MessageID"]
+      @error_code = response["ErrorCode"]
+      @message = response["Message"]
+    end
+
+    # Check if the email was sent successfully
+    #
+    # @return [Boolean] true if error_code is 0
+    def success?
+      error_code == 0
+    end
+
+    # Check if there was an error
+    #
+    # @return [Boolean] true if error_code is not 0
+    def error?
+      !success?
+    end
+
+    # Get a string representation of the response
+    #
+    # @return [String] human-readable response summary
+    def to_s
+      if success?
+        "Email sent to #{to} (Message ID: #{message_id})"
+      else
+        "Error #{error_code}: #{message}"
+      end
+    end
+
+    private
+
+    # Parse ISO 8601 timestamp string to Time object
+    #
+    # @param timestamp [String, nil] the timestamp string
+    # @return [Time, nil] parsed Time object
+    def parse_timestamp(timestamp)
+      return nil if timestamp.nil?
+
+      Time.parse(timestamp)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/postmark_client/resources/emails.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module PostmarkClient
+  module Resources
+    # Email resource client for sending emails via the Postmark API.
+    #
+    # @example Sending a simple email
+    #   emails = PostmarkClient::Resources::Emails.new
+    #   response = emails.send_email(
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Hello!",
+    #     text_body: "Hello, World!"
+    #   )
+    #
+    # @example Sending an email with an Email model
+    #   email = PostmarkClient::Email.new(
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Hello!",
+    #     html_body: "<h1>Hello, World!</h1>"
+    #   )
+    #   response = emails.send(email)
+    #
+    # @example Sending with a custom API token
+    #   emails = PostmarkClient::Resources::Emails.new(api_token: "my-token")
+    #   response = emails.send(email)
+    class Emails < Client::Base
+      # Send a single email
+      #
+      # @param email [Email, Hash] the email to send
+      # @return [EmailResponse] the API response
+      #
+      # @raise [ValidationError] if the email is invalid
+      # @raise [ApiError] if the API returns an error
+      #
+      # @example With Email model
+      #   response = emails.send(email)
+      #
+      # @example With hash
+      #   response = emails.send({
+      #     from: "sender@example.com",
+      #     to: "recipient@example.com",
+      #     subject: "Test",
+      #     text_body: "Hello"
+      #   })
+      def send(email)
+        email = normalize_email(email)
+        email.validate!
+
+        response = post("/email", email.to_h)
+        EmailResponse.new(response)
+      end
+
+      # Convenience method to send an email with parameters
+      #
+      # @param from [String] sender email address
+      # @param to [String, Array<String>] recipient email address(es)
+      # @param subject [String] email subject
+      # @param kwargs [Hash] additional email options
+      # @option kwargs [String] :html_body HTML email body
+      # @option kwargs [String] :text_body plain text email body
+      # @option kwargs [String] :cc CC recipients
+      # @option kwargs [String] :bcc BCC recipients
+      # @option kwargs [String] :reply_to reply-to address
+      # @option kwargs [String] :tag email tag
+      # @option kwargs [Boolean] :track_opens whether to track opens
+      # @option kwargs [String] :track_links link tracking setting
+      # @option kwargs [Hash] :metadata custom metadata
+      # @option kwargs [String] :message_stream message stream
+      # @return [EmailResponse] the API response
+      #
+      # @example
+      #   response = emails.send_email(
+      #     from: "sender@example.com",
+      #     to: "recipient@example.com",
+      #     subject: "Hello!",
+      #     text_body: "Hello, World!",
+      #     track_opens: true
+      #   )
+      def send_email(from:, to:, subject:, **kwargs)
+        email = Email.new(
+          from: from,
+          to: to,
+          subject: subject,
+          **kwargs
+        )
+        send(email)
+      end
+
+      # Send a batch of emails (up to 500)
+      #
+      # @param emails [Array<Email, Hash>] array of emails to send
+      # @return [Array<EmailResponse>] array of API responses
+      #
+      # @raise [ValidationError] if any email is invalid
+      # @raise [ApiError] if the API returns an error
+      # @raise [ArgumentError] if batch exceeds 500 emails
+      #
+      # @example
+      #   emails_to_send = [
+      #     { from: "a@example.com", to: "b@example.com", subject: "Hi", text_body: "Hello" },
+      #     { from: "a@example.com", to: "c@example.com", subject: "Hi", text_body: "Hello" }
+      #   ]
+      #   responses = client.send_batch(emails_to_send)
+      def send_batch(emails)
+        raise ArgumentError, "Batch cannot exceed 500 emails" if emails.length > 500
+
+        normalized = emails.map { |e| normalize_email(e) }
+        normalized.each(&:validate!)
+
+        payload = normalized.map(&:to_h)
+        responses = post("/email/batch", payload)
+
+        responses.map { |r| EmailResponse.new(r) }
+      end
+
+      private
+
+      # Normalize email input to Email model
+      #
+      # @param email [Email, Hash] the email input
+      # @return [Email] normalized email model
+      def normalize_email(email)
+        return email if email.is_a?(Email)
+
+        Email.new(**symbolize_keys(email))
+      end
+
+      # Convert hash keys to symbols
+      #
+      # @param hash [Hash] hash with string or symbol keys
+      # @return [Hash] hash with symbol keys
+      def symbolize_keys(hash)
+        hash.transform_keys do |key|
+          case key
+          when "From", :From then :from
+          when "To", :To then :to
+          when "Cc", :Cc then :cc
+          when "Bcc", :Bcc then :bcc
+          when "Subject", :Subject then :subject
+          when "HtmlBody", :HtmlBody then :html_body
+          when "TextBody", :TextBody then :text_body
+          when "ReplyTo", :ReplyTo then :reply_to
+          when "Tag", :Tag then :tag
+          when "Headers", :Headers then :headers
+          when "TrackOpens", :TrackOpens then :track_opens
+          when "TrackLinks", :TrackLinks then :track_links
+          when "Attachments", :Attachments then :attachments
+          when "Metadata", :Metadata then :metadata
+          when "MessageStream", :MessageStream then :message_stream
+          else
+            key.to_s.gsub(/([A-Z])/, '_\1').downcase.delete_prefix("_").to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/postmark_client/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PostmarkClient
+  # Current version of the PostmarkClient gem
+  # @return [String] the semantic version number
+  VERSION = "0.1.0"
+end