ark-email 0.5.1

data/rbi/ark_email/models/webhook_update_response.rbi

@@ -0,0 +1,217 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class WebhookUpdateResponse < ArkEmail::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            ArkEmail::Models::WebhookUpdateResponse,
+            ArkEmail::Internal::AnyHash
+          )
+        end
+
+      sig { returns(ArkEmail::Models::WebhookUpdateResponse::Data) }
+      attr_reader :data
+
+      sig do
+        params(data: ArkEmail::Models::WebhookUpdateResponse::Data::OrHash).void
+      end
+      attr_writer :data
+
+      sig { returns(ArkEmail::APIMeta) }
+      attr_reader :meta
+
+      sig { params(meta: ArkEmail::APIMeta::OrHash).void }
+      attr_writer :meta
+
+      sig { returns(T::Boolean) }
+      attr_accessor :success
+
+      sig do
+        params(
+          data: ArkEmail::Models::WebhookUpdateResponse::Data::OrHash,
+          meta: ArkEmail::APIMeta::OrHash,
+          success: T::Boolean
+        ).returns(T.attached_class)
+      end
+      def self.new(data:, meta:, success: true)
+      end
+
+      sig do
+        override.returns(
+          {
+            data: ArkEmail::Models::WebhookUpdateResponse::Data,
+            meta: ArkEmail::APIMeta,
+            success: T::Boolean
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Data < ArkEmail::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ArkEmail::Models::WebhookUpdateResponse::Data,
+              ArkEmail::Internal::AnyHash
+            )
+          end
+
+        # Webhook ID
+        sig { returns(String) }
+        attr_accessor :id
+
+        # Whether subscribed to all events
+        sig { returns(T::Boolean) }
+        attr_accessor :all_events
+
+        sig { returns(Time) }
+        attr_accessor :created_at
+
+        # Whether the webhook is active
+        sig { returns(T::Boolean) }
+        attr_accessor :enabled
+
+        # Subscribed events
+        sig do
+          returns(
+            T::Array[
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            ]
+          )
+        end
+        attr_accessor :events
+
+        # Webhook name for identification
+        sig { returns(String) }
+        attr_accessor :name
+
+        # Webhook endpoint URL
+        sig { returns(String) }
+        attr_accessor :url
+
+        sig { returns(String) }
+        attr_accessor :uuid
+
+        sig do
+          params(
+            id: String,
+            all_events: T::Boolean,
+            created_at: Time,
+            enabled: T::Boolean,
+            events:
+              T::Array[
+                ArkEmail::Models::WebhookUpdateResponse::Data::Event::OrSymbol
+              ],
+            name: String,
+            url: String,
+            uuid: String
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Webhook ID
+          id:,
+          # Whether subscribed to all events
+          all_events:,
+          created_at:,
+          # Whether the webhook is active
+          enabled:,
+          # Subscribed events
+          events:,
+          # Webhook name for identification
+          name:,
+          # Webhook endpoint URL
+          url:,
+          uuid:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              all_events: T::Boolean,
+              created_at: Time,
+              enabled: T::Boolean,
+              events:
+                T::Array[
+                  ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+                ],
+              name: String,
+              url: String,
+              uuid: String
+            }
+          )
+        end
+        def to_hash
+        end
+
+        module Event
+          extend ArkEmail::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                ArkEmail::Models::WebhookUpdateResponse::Data::Event
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          MESSAGE_SENT =
+            T.let(
+              :MessageSent,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_DELAYED =
+            T.let(
+              :MessageDelayed,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_DELIVERY_FAILED =
+            T.let(
+              :MessageDeliveryFailed,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_HELD =
+            T.let(
+              :MessageHeld,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_BOUNCED =
+            T.let(
+              :MessageBounced,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_LINK_CLICKED =
+            T.let(
+              :MessageLinkClicked,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_LOADED =
+            T.let(
+              :MessageLoaded,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+          DOMAIN_DNS_ERROR =
+            T.let(
+              :DomainDNSError,
+              ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                ArkEmail::Models::WebhookUpdateResponse::Data::Event::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/ark_email/models.rbi

@@ -0,0 +1,68 @@
+# typed: strong
+
+module ArkEmail
+  APIMeta = ArkEmail::Models::APIMeta
+
+  DNSRecord = ArkEmail::Models::DNSRecord
+
+  DomainCreateParams = ArkEmail::Models::DomainCreateParams
+
+  DomainDeleteParams = ArkEmail::Models::DomainDeleteParams
+
+  DomainListParams = ArkEmail::Models::DomainListParams
+
+  DomainRetrieveParams = ArkEmail::Models::DomainRetrieveParams
+
+  DomainVerifyParams = ArkEmail::Models::DomainVerifyParams
+
+  EmailListParams = ArkEmail::Models::EmailListParams
+
+  EmailRetrieveDeliveriesParams =
+    ArkEmail::Models::EmailRetrieveDeliveriesParams
+
+  EmailRetrieveParams = ArkEmail::Models::EmailRetrieveParams
+
+  EmailRetryParams = ArkEmail::Models::EmailRetryParams
+
+  EmailSendBatchParams = ArkEmail::Models::EmailSendBatchParams
+
+  EmailSendParams = ArkEmail::Models::EmailSendParams
+
+  EmailSendRawParams = ArkEmail::Models::EmailSendRawParams
+
+  SuppressionBulkCreateParams = ArkEmail::Models::SuppressionBulkCreateParams
+
+  SuppressionCreateParams = ArkEmail::Models::SuppressionCreateParams
+
+  SuppressionDeleteParams = ArkEmail::Models::SuppressionDeleteParams
+
+  SuppressionListParams = ArkEmail::Models::SuppressionListParams
+
+  SuppressionRetrieveParams = ArkEmail::Models::SuppressionRetrieveParams
+
+  TrackDomain = ArkEmail::Models::TrackDomain
+
+  TrackingCreateParams = ArkEmail::Models::TrackingCreateParams
+
+  TrackingDeleteParams = ArkEmail::Models::TrackingDeleteParams
+
+  TrackingListParams = ArkEmail::Models::TrackingListParams
+
+  TrackingRetrieveParams = ArkEmail::Models::TrackingRetrieveParams
+
+  TrackingUpdateParams = ArkEmail::Models::TrackingUpdateParams
+
+  TrackingVerifyParams = ArkEmail::Models::TrackingVerifyParams
+
+  WebhookCreateParams = ArkEmail::Models::WebhookCreateParams
+
+  WebhookDeleteParams = ArkEmail::Models::WebhookDeleteParams
+
+  WebhookListParams = ArkEmail::Models::WebhookListParams
+
+  WebhookRetrieveParams = ArkEmail::Models::WebhookRetrieveParams
+
+  WebhookTestParams = ArkEmail::Models::WebhookTestParams
+
+  WebhookUpdateParams = ArkEmail::Models::WebhookUpdateParams
+end

data/rbi/ark_email/request_options.rbi

@@ -0,0 +1,59 @@
+# typed: strong
+
+module ArkEmail
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  # or override those provided at the client level.
+  #
+  # When making a request, you can pass an actual {RequestOptions} instance, or
+  # simply pass a Hash with symbol keys matching the attributes on this class.
+  class RequestOptions < ArkEmail::Internal::Type::BaseModel
+    OrHash =
+      T.type_alias do
+        T.any(ArkEmail::RequestOptions, ArkEmail::Internal::AnyHash)
+      end
+
+    # @api private
+    sig { params(opts: ArkEmail::RequestOptions::OrHash).void }
+    def self.validate!(opts)
+    end
+
+    # Idempotency key to send with request and all associated retries. Will only be
+    # sent for write requests.
+    sig { returns(T.nilable(String)) }
+    attr_accessor :idempotency_key
+
+    # Extra query params to send with the request. These are `.merge`’d into any
+    # `query` given at the client level.
+    sig do
+      returns(
+        T.nilable(T::Hash[String, T.nilable(T.any(T::Array[String], String))])
+      )
+    end
+    attr_accessor :extra_query
+
+    # Extra headers to send with the request. These are `.merged`’d into any
+    # `extra_headers` given at the client level.
+    sig { returns(T.nilable(T::Hash[String, T.nilable(String)])) }
+    attr_accessor :extra_headers
+
+    # Extra data to send with the request. These are deep merged into any data
+    # generated as part of the normal request.
+    sig { returns(T.nilable(T.anything)) }
+    attr_accessor :extra_body
+
+    # Maximum number of retries to attempt after a failed initial request.
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :max_retries
+
+    # Request timeout in seconds.
+    sig { returns(T.nilable(Float)) }
+    attr_accessor :timeout
+
+    # Returns a new instance of RequestOptions.
+    sig do
+      params(values: ArkEmail::Internal::AnyHash).returns(T.attached_class)
+    end
+    def self.new(values = {})
+    end
+  end
+end

data/rbi/ark_email/resources/domains.rbi

@@ -0,0 +1,84 @@
+# typed: strong
+
+module ArkEmail
+  module Resources
+    class Domains
+      # Add a new domain for sending emails. Returns DNS records that must be configured
+      # before the domain can be verified.
+      #
+      # **Required DNS records:**
+      #
+      # - **SPF** - TXT record for sender authentication
+      # - **DKIM** - TXT record for email signing
+      # - **Return Path** - CNAME for bounce handling
+      #
+      # After adding DNS records, call `POST /domains/{id}/verify` to verify.
+      sig do
+        params(
+          name: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::DomainCreateResponse)
+      end
+      def create(
+        # Domain name (e.g., "mail.example.com")
+        name:,
+        request_options: {}
+      )
+      end
+
+      # Get detailed information about a domain including DNS record status
+      sig do
+        params(
+          domain_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::DomainRetrieveResponse)
+      end
+      def retrieve(
+        # Domain ID or domain name
+        domain_id,
+        request_options: {}
+      )
+      end
+
+      # Get all sending domains with their verification status
+      sig do
+        params(request_options: ArkEmail::RequestOptions::OrHash).returns(
+          ArkEmail::Models::DomainListResponse
+        )
+      end
+      def list(request_options: {})
+      end
+
+      # Remove a sending domain. You will no longer be able to send emails from this
+      # domain.
+      #
+      # **Warning:** This action cannot be undone.
+      sig do
+        params(
+          domain_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::DomainDeleteResponse)
+      end
+      def delete(domain_id, request_options: {})
+      end
+
+      # Check if DNS records are correctly configured and verify the domain. Returns the
+      # current status of each required DNS record.
+      #
+      # Call this after you've added the DNS records shown when creating the domain.
+      sig do
+        params(
+          domain_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::DomainVerifyResponse)
+      end
+      def verify(domain_id, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: ArkEmail::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/ark_email/resources/emails.rbi

@@ -0,0 +1,237 @@
+# typed: strong
+
+module ArkEmail
+  module Resources
+    class Emails
+      # Retrieve detailed information about a specific email including delivery status,
+      # timestamps, and optionally the email content.
+      #
+      # Use the `expand` parameter to include additional data like the HTML/text body,
+      # headers, or delivery attempts.
+      sig do
+        params(
+          email_id: String,
+          expand: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::EmailRetrieveResponse)
+      end
+      def retrieve(
+        # The email ID (from send response) or message token
+        email_id,
+        # Comma-separated list of fields to include:
+        #
+        # - `content` - HTML and plain text body
+        # - `headers` - Email headers
+        # - `deliveries` - Delivery attempt history
+        # - `activity` - Opens and clicks
+        expand: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a paginated list of sent emails. Results are ordered by send time,
+      # newest first.
+      #
+      # Use filters to narrow down results by status, recipient, sender, or tag.
+      #
+      # **Related endpoints:**
+      #
+      # - `GET /emails/{id}` - Get full details of a specific email
+      # - `POST /emails` - Send a new email
+      sig do
+        params(
+          after: String,
+          before: String,
+          from: String,
+          page: Integer,
+          per_page: Integer,
+          status: ArkEmail::EmailListParams::Status::OrSymbol,
+          tag: String,
+          to: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(
+          ArkEmail::Internal::PageNumberPagination[
+            ArkEmail::Models::EmailListResponse
+          ]
+        )
+      end
+      def list(
+        # Return emails sent after this timestamp (Unix seconds or ISO 8601)
+        after: nil,
+        # Return emails sent before this timestamp
+        before: nil,
+        # Filter by sender email address
+        from: nil,
+        # Page number (starts at 1)
+        page: nil,
+        # Results per page (max 100)
+        per_page: nil,
+        # Filter by delivery status:
+        #
+        # - `pending` - Email accepted, waiting to be processed
+        # - `sent` - Email transmitted to recipient's mail server
+        # - `softfail` - Temporary delivery failure, will retry
+        # - `hardfail` - Permanent delivery failure
+        # - `bounced` - Email bounced back
+        # - `held` - Held for manual review
+        status: nil,
+        # Filter by tag
+        tag: nil,
+        # Filter by recipient email address
+        to: nil,
+        request_options: {}
+      )
+      end
+
+      # Get the history of delivery attempts for an email, including SMTP response codes
+      # and timestamps.
+      sig do
+        params(
+          email_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::EmailRetrieveDeliveriesResponse)
+      end
+      def retrieve_deliveries(email_id, request_options: {})
+      end
+
+      # Retry delivery of a failed or soft-bounced email. Creates a new delivery
+      # attempt.
+      #
+      # Only works for emails that have failed or are in a retryable state.
+      sig do
+        params(
+          email_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::EmailRetryResponse)
+      end
+      def retry_(email_id, request_options: {})
+      end
+
+      # Send a single email message. The email is accepted for immediate delivery and
+      # typically delivered within seconds.
+      #
+      # **Example use case:** Send a password reset email to a user.
+      #
+      # **Required fields:** `from`, `to`, `subject`, and either `html` or `text`
+      #
+      # **Idempotency:** Supports `Idempotency-Key` header for safe retries.
+      #
+      # **Related endpoints:**
+      #
+      # - `GET /emails/{id}` - Track delivery status
+      # - `GET /emails/{id}/deliveries` - View delivery attempts
+      # - `POST /emails/{id}/retry` - Retry failed delivery
+      sig do
+        params(
+          from: String,
+          subject: String,
+          to: T::Array[String],
+          attachments: T::Array[ArkEmail::EmailSendParams::Attachment::OrHash],
+          bcc: T::Array[String],
+          cc: T::Array[String],
+          headers: T::Hash[Symbol, String],
+          html: String,
+          reply_to: String,
+          tag: String,
+          text: String,
+          idempotency_key: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::EmailSendResponse)
+      end
+      def send_(
+        # Body param: Sender email address. Must be from a verified domain.
+        #
+        # **Supported formats:**
+        #
+        # - Email only: `hello@yourdomain.com`
+        # - With display name: `Acme <hello@yourdomain.com>`
+        # - With quoted name: `"Acme Support" <support@yourdomain.com>`
+        #
+        # The domain portion must match a verified sending domain in your account.
+        from:,
+        # Body param: Email subject line
+        subject:,
+        # Body param: Recipient email addresses (max 50)
+        to:,
+        # Body param: File attachments
+        attachments: nil,
+        # Body param: BCC recipients
+        bcc: nil,
+        # Body param: CC recipients
+        cc: nil,
+        # Body param: Custom email headers
+        headers: nil,
+        # Body param: HTML body content. Maximum 5MB (5,242,880 characters). Combined with
+        # attachments, the total message must not exceed 14MB.
+        html: nil,
+        # Body param: Reply-to address
+        reply_to: nil,
+        # Body param: Tag for categorization and filtering
+        tag: nil,
+        # Body param: Plain text body (auto-generated from HTML if not provided). Maximum
+        # 5MB (5,242,880 characters).
+        text: nil,
+        # Header param: Unique key for idempotent requests. If a request with this key was
+        # already processed, the cached response is returned. Keys expire after 24 hours.
+        idempotency_key: nil,
+        request_options: {}
+      )
+      end
+
+      # Send up to 100 emails in a single request. Useful for sending personalized
+      # emails to multiple recipients efficiently.
+      #
+      # Each email in the batch can have different content and recipients. Failed emails
+      # don't affect other emails in the batch.
+      #
+      # **Idempotency:** Supports `Idempotency-Key` header for safe retries.
+      sig do
+        params(
+          emails: T::Array[ArkEmail::EmailSendBatchParams::Email::OrHash],
+          from: String,
+          idempotency_key: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::EmailSendBatchResponse)
+      end
+      def send_batch(
+        # Body param:
+        emails:,
+        # Body param: Sender email for all messages
+        from:,
+        # Header param: Unique key for idempotent requests. If a request with this key was
+        # already processed, the cached response is returned. Keys expire after 24 hours.
+        idempotency_key: nil,
+        request_options: {}
+      )
+      end
+
+      # Send a pre-formatted RFC 2822 MIME message. Use this for advanced use cases or
+      # when migrating from systems that generate raw email content.
+      #
+      # The `data` field should contain the base64-encoded raw email.
+      sig do
+        params(
+          data: String,
+          mail_from: String,
+          rcpt_to: T::Array[String],
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::EmailSendRawResponse)
+      end
+      def send_raw(
+        # Base64-encoded RFC 2822 message
+        data:,
+        # Envelope sender address
+        mail_from:,
+        # Envelope recipient addresses
+        rcpt_to:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: ArkEmail::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end