mailtrap 2.3.0 → 2.4.0

data/lib/mailtrap/client.rb

@@ -9,57 +9,193 @@ module Mailtrap
     SENDING_API_HOST = 'send.api.mailtrap.io'
     BULK_SENDING_API_HOST = 'bulk.api.mailtrap.io'
     SANDBOX_API_HOST = 'sandbox.api.mailtrap.io'
+    GENERAL_API_HOST = 'mailtrap.io'
     API_PORT = 443
 
-    attr_reader :api_key, :api_host, :api_port, :bulk, :sandbox, :inbox_id
+    attr_reader :api_key, :api_host, :general_api_host, :api_port, :bulk, :sandbox, :inbox_id
 
     # Initializes a new Mailtrap::Client instance.
     #
     # @param [String] api_key The Mailtrap API key to use for sending. Required.
-    #                         If not set, is taken from the MAILTRAP_API_KEY environment variable.
-    # @param [String, nil] api_host The Mailtrap API hostname. If not set, is chosen internally.
+    #   If not set, it is taken from the MAILTRAP_API_KEY environment variable.
+    # @param [String] api_host The Mailtrap API hostname. If not set, it is chosen internally.
+    # @param [String] general_api_host The Mailtrap general API hostname for non-sending operations.
     # @param [Integer] api_port The Mailtrap API port. Default: 443.
     # @param [Boolean] bulk Whether to use the Mailtrap bulk sending API. Default: false.
-    #                       If enabled, is incompatible with `sandbox: true`.
+    #   If enabled, it is incompatible with `sandbox: true`.
     # @param [Boolean] sandbox Whether to use the Mailtrap sandbox API. Default: false.
-    #                          If enabled, is incompatible with `bulk: true`.
+    #   If enabled, it is incompatible with `bulk: true`.
     # @param [Integer] inbox_id The sandbox inbox ID to send to. Required if sandbox API is used.
+    # @raise [ArgumentError] If api_key or api_port is nil, or if sandbox is true but inbox_id is nil,
+    #   or if incompatible options are provided.
     def initialize( # rubocop:disable Metrics/ParameterLists
       api_key: ENV.fetch('MAILTRAP_API_KEY'),
       api_host: nil,
+      general_api_host: GENERAL_API_HOST,
       api_port: API_PORT,
       bulk: false,
       sandbox: false,
       inbox_id: nil
     )
-      raise ArgumentError, 'api_key is required' if api_key.nil?
-      raise ArgumentError, 'api_port is required' if api_port.nil?
+      validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
 
       api_host ||= select_api_host(bulk:, sandbox:)
-      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
 
       @api_key = api_key
       @api_host = api_host
+      @general_api_host = general_api_host
       @api_port = api_port
       @bulk = bulk
       @sandbox = sandbox
       @inbox_id = inbox_id
+      @http_clients = {}
+    end
+
+    # Sends a batch of emails.
+    # @example Batch sending with template
+    #   batch_base = Mailtrap::Mail.batch_base_from_template(
+    #     from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
+    #     reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
+    #     template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
+    #   )
+    #
+    #   client.send_batch(
+    #     batch_base, [
+    #       Mailtrap::Mail.from_template(
+    #         to: [
+    #           { email: 'john.doe@email.com', name: 'John Doe' }
+    #         ],
+    #         template_variables: {
+    #           user_name: 'John Doe'
+    #         }
+    #       ),
+    #       Mailtrap::Mail::Base.new(
+    #         to: [
+    #           { email: 'jane.doe@email.com', name: 'Jane Doe' }
+    #         ],
+    #         template_variables: {
+    #           user_name: 'Jane Doe'
+    #         }
+    #       ),
+    #       {
+    #         to: [
+    #           { email: 'david.doe@email.com', name: 'David Doe' }
+    #         ],
+    #         template_variables: {
+    #           user_name: 'David Doe'
+    #         }
+    #       }
+    #     ]
+    #   )
+    #
+    # @example Passing the request parameters directly
+    #   client.send_batch(
+    #     {
+    #       from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
+    #       reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
+    #       template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
+    #     }, [
+    #       {
+    #         to: [
+    #           { email: 'john.doe@email.com', name: 'John Doe' }
+    #         ],
+    #         template_variables: {
+    #           user_name: 'John Doe'
+    #         }
+    #       },
+    #       {
+    #         to: [
+    #           { email: 'jane.doe@email.com', name: 'Jane Doe' }
+    #         ],
+    #         template_variables: {
+    #           user_name: 'Jane Doe'
+    #         }
+    #       }
+    #     ]
+    #   )
+    # @param base [#to_json] The base email configuration for the batch.
+    # @param requests [Array<#to_json>] Array of individual email requests.
+    # @return [Hash] The JSON response from the API.
+    # @!macro api_errors
+    # @raise [Mailtrap::MailSizeError] If the message is too large.
+    def send_batch(base, requests)
+      perform_request(:post, api_host, batch_request_path, {
+                        base:,
+                        requests:
+                      })
     end
 
+    # Sends an email
+    # @example
+    #   mail = Mailtrap::Mail.from_template(
+    #     from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
+    #     to: [
+    #       { email: 'your@email.com' }
+    #     ],
+    #     template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+    #     template_variables: {
+    #       'user_name' => 'John Doe'
+    #     }
+    #   )
+    #   client.send(mail)
+    # @example
+    #   client.send(
+    #     from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
+    #     to: [
+    #       { email: 'your@email.com' }
+    #     ],
+    #     subject: 'You are awesome!',
+    #     text: 'Congrats for sending test email with Mailtrap!'
+    #   )
+    # @param mail [#to_json] The email to send
+    # @return [Hash] The JSON response
+    # @!macro api_errors
+    # @raise [Mailtrap::MailSizeError] If the message is too large
     def send(mail)
-      raise ArgumentError, 'should be Mailtrap::Mail::Base object' unless mail.is_a? Mail::Base
+      perform_request(:post, api_host, send_path, mail)
+    end
 
-      request = post_request(request_url, mail.to_json)
-      response = http_client.request(request)
+    # Performs a GET request to the specified path
+    # @param path [String] The request path
+    # @return [Hash, nil] The JSON response
+    # @!macro api_errors
+    def get(path)
+      perform_request(:get, general_api_host, path)
+    end
 
-      handle_response(response)
+    # Performs a POST request to the specified path
+    # @param path [String] The request path
+    # @param body [Hash] The request body
+    # @return [Hash, nil] The JSON response
+    # @!macro api_errors
+    def post(path, body = nil)
+      perform_request(:post, general_api_host, path, body)
+    end
+
+    # Performs a PATCH request to the specified path
+    # @param path [String] The request path
+    # @param body [Hash] The request body
+    # @return [Hash, nil] The JSON response
+    # @!macro api_errors
+    def patch(path, body = nil)
+      perform_request(:patch, general_api_host, path, body)
+    end
+
+    # Performs a DELETE request to the specified path
+    # @param path [String] The request path
+    # @return [Hash, nil] The JSON response
+    # @!macro api_errors
+    def delete(path)
+      perform_request(:delete, general_api_host, path)
     end
 
     private
 
-    def select_api_host(bulk:, sandbox:)
-      raise ArgumentError, 'bulk mode is not applicable for sandbox API' if bulk && sandbox
+    def http_client_for(host)
+      @http_clients[host] ||= Net::HTTP.new(host, api_port).tap { |client| client.use_ssl = true }
+    end
 
+    def select_api_host(bulk:, sandbox:)
       if sandbox
         SANDBOX_API_HOST
       elsif bulk
@@ -69,17 +205,36 @@ module Mailtrap
       end
     end
 
-    def request_url
-      "/api/send#{sandbox ? "/#{inbox_id}" : ""}"
+    def send_path
+      "/api/send#{"/#{inbox_id}" if sandbox}"
+    end
+
+    def batch_request_path
+      "/api/batch#{"/#{inbox_id}" if sandbox}"
     end
 
-    def http_client
-      @http_client ||= Net::HTTP.new(api_host, api_port).tap { |client| client.use_ssl = true }
+    def perform_request(method, host, path, body = nil)
+      http_client = http_client_for(host)
+      request = setup_request(method, path, body)
+      response = http_client.request(request)
+      handle_response(response)
     end
 
-    def post_request(path, body)
-      request = Net::HTTP::Post.new(path)
-      request.body = body
+    def setup_request(method, path, body = nil)
+      request = case method
+                when :get
+                  Net::HTTP::Get.new(path)
+                when :post
+                  Net::HTTP::Post.new(path)
+                when :patch
+                  Net::HTTP::Patch.new(path)
+                when :delete
+                  Net::HTTP::Delete.new(path)
+                else
+                  raise ArgumentError, "Unsupported HTTP method: #{method}"
+                end
+
+      request.body = body.to_json if body
       request['Authorization'] = "Bearer #{api_key}"
       request['Content-Type'] = 'application/json'
       request['User-Agent'] = 'mailtrap-ruby (https://github.com/railsware/mailtrap-ruby)'
@@ -87,22 +242,26 @@ module Mailtrap
       request
     end
 
-    def handle_response(response) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+    def handle_response(response) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
       case response
-      when Net::HTTPOK
+      when Net::HTTPOK, Net::HTTPCreated
         json_response(response.body)
+      when Net::HTTPNoContent
+        nil
       when Net::HTTPBadRequest
-        raise Mailtrap::Error, json_response(response.body)[:errors]
+        raise Mailtrap::Error, ['bad request'] if response.body.empty?
+
+        raise Mailtrap::Error, response_errors(response.body)
       when Net::HTTPUnauthorized
-        raise Mailtrap::AuthorizationError, json_response(response.body)[:errors]
+        raise Mailtrap::AuthorizationError, response_errors(response.body)
       when Net::HTTPForbidden
-        raise Mailtrap::RejectionError, json_response(response.body)[:errors]
+        raise Mailtrap::RejectionError, response_errors(response.body)
       when Net::HTTPPayloadTooLarge
         raise Mailtrap::MailSizeError, ['message too large']
       when Net::HTTPTooManyRequests
         raise Mailtrap::RateLimitError, ['too many requests']
       when Net::HTTPClientError
-        raise Mailtrap::Error, ['client error']
+        raise Mailtrap::Error, ["client error '#{response.body}'"]
       when Net::HTTPServerError
         raise Mailtrap::Error, ['server error']
       else
@@ -110,8 +269,20 @@ module Mailtrap
       end
     end
 
+    def response_errors(body)
+      parsed_body = json_response(body)
+      Array(parsed_body[:errors] || parsed_body[:error])
+    end
+
     def json_response(body)
       JSON.parse(body, symbolize_names: true)
     end
+
+    def validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
+      raise ArgumentError, 'api_key is required' if api_key.nil?
+      raise ArgumentError, 'api_port is required' if api_port.nil?
+      raise ArgumentError, 'bulk stream is not applicable for sandbox API' if bulk && sandbox
+      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
+    end
   end
 end

data/lib/mailtrap/contact.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/220a54e31e5ca-contact
+  # @attr_reader id [String] The contact ID
+  # @attr_reader email [String] The contact's email address
+  # @attr_reader fields [Hash] Object of fields with merge tags
+  # @attr_reader list_ids [Array<Integer>] Array of list IDs
+  # @attr_reader status [String] The contact status (subscribed/unsubscribed)
+  # @attr_reader created_at [Integer] The creation timestamp
+  # @attr_reader updated_at [Integer] The last update timestamp
+  Contact = Struct.new(
+    :id,
+    :email,
+    :fields,
+    :list_ids,
+    :status,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  ) do
+    def initialize(options)
+      @action = options[:action]
+      super(options.except(:action))
+    end
+
+    # @return [Boolean] Whether the contact was newly created
+    def newly_created?
+      @action != 'updated'
+    end
+
+    # @return [Hash] The contact attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

data/lib/mailtrap/contact_field.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact Field
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/33efe96c91dcc-get-all-contact-fields
+  # @attr_reader id [Integer] The contact field ID
+  # @attr_reader name [String] The name of the contact field (max 80 characters)
+  # @attr_reader data_type [String] The data type of the field
+  #   Allowed values: text, integer, float, boolean, date
+  # @attr_reader merge_tag [String] Personalize your campaigns by adding a merge tag.
+  #   This field will be replaced with unique contact details for each recipient (max 80 characters)
+  ContactField = Struct.new(:id, :name, :data_type, :merge_tag, keyword_init: true) do
+    # @return [Hash] The contact field attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

data/lib/mailtrap/contact_fields_api.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'contact_field'
+
+module Mailtrap
+  class ContactFieldsAPI
+    include BaseAPI
+
+    self.supported_options = %i[name data_type merge_tag]
+
+    self.response_class = ContactField
+
+    # Retrieves a specific contact field
+    # @param field_id [Integer] The contact field identifier
+    # @return [ContactField] Contact field object
+    # @!macro api_errors
+    def get(field_id)
+      base_get(field_id)
+    end
+
+    # Creates a new contact field
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The contact field name
+    # @option options [String] :data_type The data type of the field
+    # @option options [String] :merge_tag The merge tag of the field
+    # @return [ContactField] Created contact field object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing contact field
+    # @param field_id [Integer] The contact field ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The contact field name
+    # @option options [String] :merge_tag The merge tag of the field
+    # @return [ContactField] Updated contact field object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(field_id, options)
+      base_update(field_id, options, %i[name merge_tag])
+    end
+
+    # Deletes a contact field
+    # @param field_id [Integer] The contact field ID
+    # @return nil
+    # @!macro api_errors
+    def delete(field_id)
+      base_delete(field_id)
+    end
+
+    # Lists all contact fields for the account
+    # @return [Array<ContactField>] Array of contact field objects
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/fields"
+    end
+  end
+end

data/lib/mailtrap/contact_list.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Contact List
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/6ec7a37234af2-contact-list
+  # @attr_reader id [Integer] The contact list ID
+  # @attr_reader name [String] The name of the contact list
+  ContactList = Struct.new(:id, :name, keyword_init: true) do
+    # @return [Hash] The contact list attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end

data/lib/mailtrap/contact_lists_api.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'contact_list'
+
+module Mailtrap
+  class ContactListsAPI
+    include BaseAPI
+
+    self.supported_options = %i[name]
+
+    self.response_class = ContactList
+
+    # Retrieves a specific contact list
+    # @param list_id [Integer] The contact list identifier
+    # @return [ContactList] Contact list object
+    # @!macro api_errors
+    def get(list_id)
+      base_get(list_id)
+    end
+
+    # Creates a new contact list
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The contact list name
+    # @return [ContactList] Created contact list object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing contact list
+    # @param list_id [Integer] The contact list ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The contact list name
+    # @return [ContactList] Updated contact list object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(list_id, options)
+      base_update(list_id, options)
+    end
+
+    # Deletes a contact list
+    # @param list_id [Integer] The contact list ID
+    # @return nil
+    # @!macro api_errors
+    def delete(list_id)
+      base_delete(list_id)
+    end
+
+    # Lists all contact lists for the account
+    # @return [Array<ContactList>] Array of contact list objects
+    # @!macro api_errors
+    def list
+      base_list
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts/lists"
+    end
+  end
+end

data/lib/mailtrap/contacts_api.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'contact'
+
+module Mailtrap
+  class ContactsAPI
+    include BaseAPI
+
+    self.supported_options = %i[email fields list_ids]
+    self.response_class = Contact
+
+    # Retrieves a specific contact
+    # @param contact_id [String] The contact identifier, which can be either a UUID or an email address
+    # @return [Contact] Contact object
+    # @!macro api_errors
+    def get(contact_id)
+      base_get(contact_id)
+    end
+
+    # Creates a new contact
+    # @param [Hash] options The parameters to create
+    # @option options [String] :email The contact's email address
+    # @option options [Hash] :fields The contact's fields
+    # @option options [Array<Integer>] :list_ids The contact's list IDs
+    # @return [Contact] Created contact object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Deletes a contact
+    # @param contact_id [String] The contact ID
+    # @return nil
+    # @!macro api_errors
+    def delete(contact_id)
+      base_delete(contact_id)
+    end
+
+    # Updates an existing contact or creates a new one if it doesn't exist
+    # @param contact_id [String] The contact ID or email address
+    # @param [Hash] options The parameters to update
+    # @option options [String] :email The contact's email address
+    # @option options [Hash] :fields The contact's fields
+    # @option options [Boolean] :unsubscribed Whether to unsubscribe the contact
+    # @return [Contact] Updated contact object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def upsert(contact_id, options)
+      base_update(contact_id, options, %i[email fields unsubscribed])
+    end
+
+    # Adds a contact to specified lists
+    # @param contact_id [String] The contact ID or email address
+    # @param contact_list_ids [Array<Integer>] Array of list IDs to add the contact to
+    # @return [Contact] Updated contact object
+    # @!macro api_errors
+    def add_to_lists(contact_id, contact_list_ids = [])
+      update_lists(contact_id, list_ids_included: contact_list_ids)
+    end
+
+    # Removes a contact from specified lists
+    # @param contact_id [String] The contact ID or email address
+    # @param contact_list_ids [Array<Integer>] Array of list IDs to remove the contact from
+    # @return [Contact] Updated contact object
+    # @!macro api_errors
+    def remove_from_lists(contact_id, contact_list_ids = [])
+      update_lists(contact_id, list_ids_excluded: contact_list_ids)
+    end
+
+    private
+
+    def update_lists(contact_id, options)
+      base_update(contact_id, options, %i[list_ids_included list_ids_excluded])
+    end
+
+    def wrap_request(options)
+      { contact: options }
+    end
+
+    def handle_response(response)
+      response_class.new response[:data].slice(*response_class.members).merge(action: response[:action])
+    end
+
+    def base_path
+      "/api/accounts/#{account_id}/contacts"
+    end
+  end
+end

data/lib/mailtrap/email_template.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Email Template
+  #
+  # For field descriptions and response format, see the official API documentation:
+  # @see https://api-docs.mailtrap.io/docs/mailtrap-api-docs/9e5914d89c481-email-template
+  #
+  # @attr_reader id [Integer] The template ID
+  # @attr_reader uuid [String] The template UUID
+  # @attr_reader name [String] The template name
+  # @attr_reader subject [String] The email subject
+  # @attr_reader category [String] The template category
+  # @attr_reader body_html [String] The HTML content
+  # @attr_reader body_text [String] The plain text content
+  # @attr_reader created_at [String] The creation timestamp
+  # @attr_reader updated_at [String] The last update timestamp
+  EmailTemplate = Struct.new(
+    :id,
+    :uuid,
+    :name,
+    :subject,
+    :category,
+    :body_html,
+    :body_text,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  ) do
+    # @return [Hash] The template attributes as a hash
+    def to_h
+      super.compact
+    end
+  end
+end