ark-email 0.17.0 → 0.18.0

data/lib/ark_email/models/tenant_update_params.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Tenants#update
+    class TenantUpdateParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!attribute metadata
+      #   Custom key-value pairs. Useful for storing references to your internal systems.
+      #
+      #   **Limits:**
+      #
+      #   - Max 50 keys
+      #   - Key names max 40 characters
+      #   - String values max 500 characters
+      #   - Total size max 8KB
+      #
+      #   @return [Hash{Symbol=>String, Float, Boolean, nil}, nil]
+      optional :metadata,
+               -> {
+                 ArkEmail::Internal::Type::HashOf[union: ArkEmail::TenantUpdateParams::Metadata, nil?: true]
+               },
+               nil?: true
+
+      # @!attribute name
+      #   Display name for the tenant
+      #
+      #   @return [String, nil]
+      optional :name, String
+
+      # @!attribute status
+      #   Tenant status
+      #
+      #   @return [Symbol, ArkEmail::Models::TenantUpdateParams::Status, nil]
+      optional :status, enum: -> { ArkEmail::TenantUpdateParams::Status }
+
+      # @!method initialize(metadata: nil, name: nil, status: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {ArkEmail::Models::TenantUpdateParams} for more details.
+      #
+      #   @param metadata [Hash{Symbol=>String, Float, Boolean, nil}, nil] Custom key-value pairs. Useful for storing references to your internal systems.
+      #
+      #   @param name [String] Display name for the tenant
+      #
+      #   @param status [Symbol, ArkEmail::Models::TenantUpdateParams::Status] Tenant status
+      #
+      #   @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}]
+
+      module Metadata
+        extend ArkEmail::Internal::Type::Union
+
+        variant String
+
+        variant Float
+
+        variant ArkEmail::Internal::Type::Boolean
+
+        # @!method self.variants
+        #   @return [Array(String, Float, Boolean)]
+      end
+
+      # Tenant status
+      module Status
+        extend ArkEmail::Internal::Type::Enum
+
+        ACTIVE = :active
+        SUSPENDED = :suspended
+        ARCHIVED = :archived
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/ark_email/models/tenant_update_response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Tenants#update
+    class TenantUpdateResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [ArkEmail::Models::Tenant]
+      required :data, -> { ArkEmail::Tenant }
+
+      # @!attribute meta
+      #
+      #   @return [ArkEmail::Models::APIMeta]
+      required :meta, -> { ArkEmail::APIMeta }
+
+      # @!attribute success
+      #
+      #   @return [Boolean, true]
+      required :success, const: true
+
+      # @!method initialize(data:, meta:, success: true)
+      #   @param data [ArkEmail::Models::Tenant]
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #   @param success [Boolean, true]
+    end
+  end
+end

data/lib/ark_email/models.rb

@@ -85,6 +85,18 @@ module ArkEmail
 
   SuppressionRetrieveParams = ArkEmail::Models::SuppressionRetrieveParams
 
+  Tenant = ArkEmail::Models::Tenant
+
+  TenantCreateParams = ArkEmail::Models::TenantCreateParams
+
+  TenantDeleteParams = ArkEmail::Models::TenantDeleteParams
+
+  TenantListParams = ArkEmail::Models::TenantListParams
+
+  TenantRetrieveParams = ArkEmail::Models::TenantRetrieveParams
+
+  TenantUpdateParams = ArkEmail::Models::TenantUpdateParams
+
   TrackDomain = ArkEmail::Models::TrackDomain
 
   TrackingCreateParams = ArkEmail::Models::TrackingCreateParams

data/lib/ark_email/resources/tenants.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Tenants
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::TenantCreateParams} for more details.
+      #
+      # Create a new tenant.
+      #
+      # Returns the created tenant with a unique `id`. Store this ID in your database to
+      # reference this tenant later.
+      #
+      # @overload create(name:, metadata: nil, request_options: {})
+      #
+      # @param name [String] Display name for the tenant (e.g., your customer's company name)
+      #
+      # @param metadata [Hash{Symbol=>String, Float, Boolean, nil}, nil] Custom key-value pairs. Useful for storing references to your internal systems.
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TenantCreateResponse]
+      #
+      # @see ArkEmail::Models::TenantCreateParams
+      def create(params)
+        parsed, options = ArkEmail::TenantCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "tenants",
+          body: parsed,
+          model: ArkEmail::Models::TenantCreateResponse,
+          options: options
+        )
+      end
+
+      # Get a tenant by ID.
+      #
+      # @overload retrieve(tenant_id, request_options: {})
+      #
+      # @param tenant_id [String] The tenant ID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TenantRetrieveResponse]
+      #
+      # @see ArkEmail::Models::TenantRetrieveParams
+      def retrieve(tenant_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["tenants/%1$s", tenant_id],
+          model: ArkEmail::Models::TenantRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::TenantUpdateParams} for more details.
+      #
+      # Update a tenant's name, metadata, or status. At least one field is required.
+      #
+      # Metadata is replaced entirely—include all keys you want to keep.
+      #
+      # @overload update(tenant_id, metadata: nil, name: nil, status: nil, request_options: {})
+      #
+      # @param tenant_id [String] The tenant ID
+      #
+      # @param metadata [Hash{Symbol=>String, Float, Boolean, nil}, nil] Custom key-value pairs. Useful for storing references to your internal systems.
+      #
+      # @param name [String] Display name for the tenant
+      #
+      # @param status [Symbol, ArkEmail::Models::TenantUpdateParams::Status] Tenant status
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TenantUpdateResponse]
+      #
+      # @see ArkEmail::Models::TenantUpdateParams
+      def update(tenant_id, params = {})
+        parsed, options = ArkEmail::TenantUpdateParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["tenants/%1$s", tenant_id],
+          body: parsed,
+          model: ArkEmail::Models::TenantUpdateResponse,
+          options: options
+        )
+      end
+
+      # List all tenants with pagination. Filter by `status` if needed.
+      #
+      # @overload list(page: nil, per_page: nil, status: nil, request_options: {})
+      #
+      # @param page [Integer] Page number (1-indexed)
+      #
+      # @param per_page [Integer] Number of items per page (max 100)
+      #
+      # @param status [Symbol, ArkEmail::Models::TenantListParams::Status] Filter by tenant status
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Internal::PageNumberPagination<ArkEmail::Models::Tenant>]
+      #
+      # @see ArkEmail::Models::TenantListParams
+      def list(params = {})
+        parsed, options = ArkEmail::TenantListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "tenants",
+          query: parsed.transform_keys(per_page: "perPage"),
+          page: ArkEmail::Internal::PageNumberPagination,
+          model: ArkEmail::Tenant,
+          options: options
+        )
+      end
+
+      # Permanently delete a tenant. This cannot be undone.
+      #
+      # @overload delete(tenant_id, request_options: {})
+      #
+      # @param tenant_id [String] The tenant ID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TenantDeleteResponse]
+      #
+      # @see ArkEmail::Models::TenantDeleteParams
+      def delete(tenant_id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["tenants/%1$s", tenant_id],
+          model: ArkEmail::Models::TenantDeleteResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/ark_email/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArkEmail
-  VERSION = "0.17.0"
+  VERSION = "0.18.0"
 end

data/lib/ark_email.rb

@@ -94,6 +94,16 @@ require_relative "ark_email/models/suppression_list_params"
 require_relative "ark_email/models/suppression_list_response"
 require_relative "ark_email/models/suppression_retrieve_params"
 require_relative "ark_email/models/suppression_retrieve_response"
+require_relative "ark_email/models/tenant"
+require_relative "ark_email/models/tenant_create_params"
+require_relative "ark_email/models/tenant_create_response"
+require_relative "ark_email/models/tenant_delete_params"
+require_relative "ark_email/models/tenant_delete_response"
+require_relative "ark_email/models/tenant_list_params"
+require_relative "ark_email/models/tenant_retrieve_params"
+require_relative "ark_email/models/tenant_retrieve_response"
+require_relative "ark_email/models/tenant_update_params"
+require_relative "ark_email/models/tenant_update_response"
 require_relative "ark_email/models/track_domain"
 require_relative "ark_email/models/tracking_create_params"
 require_relative "ark_email/models/tracking_create_response"
@@ -132,6 +142,7 @@ require_relative "ark_email/resources/domains"
 require_relative "ark_email/resources/emails"
 require_relative "ark_email/resources/logs"
 require_relative "ark_email/resources/suppressions"
+require_relative "ark_email/resources/tenants"
 require_relative "ark_email/resources/tracking"
 require_relative "ark_email/resources/usage"
 require_relative "ark_email/resources/webhooks"

data/rbi/ark_email/client.rbi

@@ -40,6 +40,9 @@ module ArkEmail
     sig { returns(ArkEmail::Resources::Usage) }
     attr_reader :usage
 
+    sig { returns(ArkEmail::Resources::Tenants) }
+    attr_reader :tenants
+
     # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers

data/rbi/ark_email/models/email_retrieve_deliveries_response.rbi

@@ -205,6 +205,25 @@ module ArkEmail
           sig { returns(Time) }
           attr_accessor :timestamp_iso
 
+          # Bounce classification category (present for failed deliveries). Helps understand
+          # why delivery failed for analytics and automated handling.
+          sig do
+            returns(
+              T.nilable(
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            )
+          end
+          attr_accessor :classification
+
+          # Numeric bounce classification code for programmatic handling. Codes:
+          # 10=invalid_recipient, 11=no_mailbox, 12=not_accepting_mail, 20=mailbox_full,
+          # 21=message_too_large, 30=spam_block, 31=policy_violation, 32=tls_required,
+          # 40=connection_error, 41=dns_error, 42=temporarily_unavailable,
+          # 50=protocol_error, 99=unclassified
+          sig { returns(T.nilable(Integer)) }
+          attr_accessor :classification_code
+
           # SMTP response code
           sig { returns(T.nilable(Integer)) }
           attr_reader :code
@@ -212,20 +231,29 @@ module ArkEmail
           sig { params(code: Integer).void }
           attr_writer :code
 
-          # Status details
+          # Human-readable delivery summary. Format varies by status:
+          #
+          # - **sent**: `Message for {recipient} accepted by {ip}:{port} ({hostname})`
+          # - **softfail/hardfail**:
+          #   `{code} {classification}: Delivery to {recipient} failed at {ip}:{port} ({hostname})`
           sig { returns(T.nilable(String)) }
           attr_reader :details
 
           sig { params(details: String).void }
           attr_writer :details
 
-          # SMTP server response from the receiving mail server
+          # Raw SMTP response from the receiving mail server
           sig { returns(T.nilable(String)) }
           attr_reader :output
 
           sig { params(output: String).void }
           attr_writer :output
 
+          # Hostname of the remote mail server that processed the delivery. Present for all
+          # delivery attempts (successful and failed).
+          sig { returns(T.nilable(String)) }
+          attr_accessor :remote_host
+
           # Whether TLS was used
           sig { returns(T.nilable(T::Boolean)) }
           attr_reader :sent_with_ssl
@@ -233,16 +261,29 @@ module ArkEmail
           sig { params(sent_with_ssl: T::Boolean).void }
           attr_writer :sent_with_ssl
 
+          # RFC 3463 enhanced status code from SMTP response (e.g., "5.1.1", "4.2.2"). First
+          # digit: 2=success, 4=temporary, 5=permanent. Second digit: category (1=address,
+          # 2=mailbox, 7=security, etc.).
+          sig { returns(T.nilable(String)) }
+          attr_accessor :smtp_enhanced_code
+
           sig do
             params(
               id: String,
               status: String,
               timestamp: Float,
               timestamp_iso: Time,
+              classification:
+                T.nilable(
+                  ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::OrSymbol
+                ),
+              classification_code: T.nilable(Integer),
               code: Integer,
               details: String,
               output: String,
-              sent_with_ssl: T::Boolean
+              remote_host: T.nilable(String),
+              sent_with_ssl: T::Boolean,
+              smtp_enhanced_code: T.nilable(String)
             ).returns(T.attached_class)
           end
           def self.new(
@@ -254,14 +295,34 @@ module ArkEmail
             timestamp:,
             # ISO 8601 timestamp
             timestamp_iso:,
+            # Bounce classification category (present for failed deliveries). Helps understand
+            # why delivery failed for analytics and automated handling.
+            classification: nil,
+            # Numeric bounce classification code for programmatic handling. Codes:
+            # 10=invalid_recipient, 11=no_mailbox, 12=not_accepting_mail, 20=mailbox_full,
+            # 21=message_too_large, 30=spam_block, 31=policy_violation, 32=tls_required,
+            # 40=connection_error, 41=dns_error, 42=temporarily_unavailable,
+            # 50=protocol_error, 99=unclassified
+            classification_code: nil,
             # SMTP response code
             code: nil,
-            # Status details
+            # Human-readable delivery summary. Format varies by status:
+            #
+            # - **sent**: `Message for {recipient} accepted by {ip}:{port} ({hostname})`
+            # - **softfail/hardfail**:
+            #   `{code} {classification}: Delivery to {recipient} failed at {ip}:{port} ({hostname})`
             details: nil,
-            # SMTP server response from the receiving mail server
+            # Raw SMTP response from the receiving mail server
             output: nil,
+            # Hostname of the remote mail server that processed the delivery. Present for all
+            # delivery attempts (successful and failed).
+            remote_host: nil,
             # Whether TLS was used
-            sent_with_ssl: nil
+            sent_with_ssl: nil,
+            # RFC 3463 enhanced status code from SMTP response (e.g., "5.1.1", "4.2.2"). First
+            # digit: 2=success, 4=temporary, 5=permanent. Second digit: category (1=address,
+            # 2=mailbox, 7=security, etc.).
+            smtp_enhanced_code: nil
           )
           end
 
@@ -272,15 +333,113 @@ module ArkEmail
                 status: String,
                 timestamp: Float,
                 timestamp_iso: Time,
+                classification:
+                  T.nilable(
+                    ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+                  ),
+                classification_code: T.nilable(Integer),
                 code: Integer,
                 details: String,
                 output: String,
-                sent_with_ssl: T::Boolean
+                remote_host: T.nilable(String),
+                sent_with_ssl: T::Boolean,
+                smtp_enhanced_code: T.nilable(String)
               }
             )
           end
           def to_hash
           end
+
+          # Bounce classification category (present for failed deliveries). Helps understand
+          # why delivery failed for analytics and automated handling.
+          module Classification
+            extend ArkEmail::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            INVALID_RECIPIENT =
+              T.let(
+                :invalid_recipient,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            MAILBOX_FULL =
+              T.let(
+                :mailbox_full,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            MESSAGE_TOO_LARGE =
+              T.let(
+                :message_too_large,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            SPAM_BLOCK =
+              T.let(
+                :spam_block,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            POLICY_VIOLATION =
+              T.let(
+                :policy_violation,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            NO_MAILBOX =
+              T.let(
+                :no_mailbox,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            NOT_ACCEPTING_MAIL =
+              T.let(
+                :not_accepting_mail,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            TEMPORARILY_UNAVAILABLE =
+              T.let(
+                :temporarily_unavailable,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            PROTOCOL_ERROR =
+              T.let(
+                :protocol_error,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            TLS_REQUIRED =
+              T.let(
+                :tls_required,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            CONNECTION_ERROR =
+              T.let(
+                :connection_error,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            DNS_ERROR =
+              T.let(
+                :dns_error,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+            UNCLASSIFIED =
+              T.let(
+                :unclassified,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::Classification::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
         end
 
         class RetryState < ArkEmail::Internal::Type::BaseModel