ark-email 0.5.1

data/lib/ark_email/resources/emails.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Emails
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::EmailRetrieveParams} for more details.
+      #
+      # 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.
+      #
+      # @overload retrieve(email_id, expand: nil, request_options: {})
+      #
+      # @param email_id [String] The email ID (from send response) or message token
+      #
+      # @param expand [String] Comma-separated list of fields to include:
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::EmailRetrieveResponse]
+      #
+      # @see ArkEmail::Models::EmailRetrieveParams
+      def retrieve(email_id, params = {})
+        parsed, options = ArkEmail::EmailRetrieveParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["emails/%1$s", email_id],
+          query: parsed,
+          model: ArkEmail::Models::EmailRetrieveResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::EmailListParams} for more details.
+      #
+      # 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
+      #
+      # @overload list(after: nil, before: nil, from: nil, page: nil, per_page: nil, status: nil, tag: nil, to: nil, request_options: {})
+      #
+      # @param after [String] Return emails sent after this timestamp (Unix seconds or ISO 8601)
+      #
+      # @param before [String] Return emails sent before this timestamp
+      #
+      # @param from [String] Filter by sender email address
+      #
+      # @param page [Integer] Page number (starts at 1)
+      #
+      # @param per_page [Integer] Results per page (max 100)
+      #
+      # @param status [Symbol, ArkEmail::Models::EmailListParams::Status] Filter by delivery status:
+      #
+      # @param tag [String] Filter by tag
+      #
+      # @param to [String] Filter by recipient email address
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Internal::PageNumberPagination<ArkEmail::Models::EmailListResponse>]
+      #
+      # @see ArkEmail::Models::EmailListParams
+      def list(params = {})
+        parsed, options = ArkEmail::EmailListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "emails",
+          query: parsed.transform_keys(per_page: "perPage"),
+          page: ArkEmail::Internal::PageNumberPagination,
+          model: ArkEmail::Models::EmailListResponse,
+          options: options
+        )
+      end
+
+      # Get the history of delivery attempts for an email, including SMTP response codes
+      # and timestamps.
+      #
+      # @overload retrieve_deliveries(email_id, request_options: {})
+      #
+      # @param email_id [String]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::EmailRetrieveDeliveriesResponse]
+      #
+      # @see ArkEmail::Models::EmailRetrieveDeliveriesParams
+      def retrieve_deliveries(email_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["emails/%1$s/deliveries", email_id],
+          model: ArkEmail::Models::EmailRetrieveDeliveriesResponse,
+          options: params[: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.
+      #
+      # @overload retry_(email_id, request_options: {})
+      #
+      # @param email_id [String]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::EmailRetryResponse]
+      #
+      # @see ArkEmail::Models::EmailRetryParams
+      def retry_(email_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["emails/%1$s/retry", email_id],
+          model: ArkEmail::Models::EmailRetryResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::EmailSendParams} for more details.
+      #
+      # 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
+      #
+      # @overload send_(from:, subject:, to:, attachments: nil, bcc: nil, cc: nil, headers: nil, html: nil, reply_to: nil, tag: nil, text: nil, idempotency_key: nil, request_options: {})
+      #
+      # @param from [String] Body param: Sender email address. Must be from a verified domain.
+      #
+      # @param subject [String] Body param: Email subject line
+      #
+      # @param to [Array<String>] Body param: Recipient email addresses (max 50)
+      #
+      # @param attachments [Array<ArkEmail::Models::EmailSendParams::Attachment>] Body param: File attachments
+      #
+      # @param bcc [Array<String>] Body param: BCC recipients
+      #
+      # @param cc [Array<String>] Body param: CC recipients
+      #
+      # @param headers [Hash{Symbol=>String}] Body param: Custom email headers
+      #
+      # @param html [String] Body param: HTML body content.
+      #
+      # @param reply_to [String] Body param: Reply-to address
+      #
+      # @param tag [String] Body param: Tag for categorization and filtering
+      #
+      # @param text [String] Body param: Plain text body (auto-generated from HTML if not provided).
+      #
+      # @param idempotency_key [String] Header param: Unique key for idempotent requests. If a request with this key was
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::EmailSendResponse]
+      #
+      # @see ArkEmail::Models::EmailSendParams
+      def send_(params)
+        parsed, options = ArkEmail::EmailSendParams.dump_request(params)
+        header_params = {idempotency_key: "idempotency-key"}
+        @client.request(
+          method: :post,
+          path: "emails",
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: ArkEmail::Models::EmailSendResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::EmailSendBatchParams} for more details.
+      #
+      # 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.
+      #
+      # @overload send_batch(emails:, from:, idempotency_key: nil, request_options: {})
+      #
+      # @param emails [Array<ArkEmail::Models::EmailSendBatchParams::Email>] Body param:
+      #
+      # @param from [String] Body param: Sender email for all messages
+      #
+      # @param idempotency_key [String] Header param: Unique key for idempotent requests. If a request with this key was
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::EmailSendBatchResponse]
+      #
+      # @see ArkEmail::Models::EmailSendBatchParams
+      def send_batch(params)
+        parsed, options = ArkEmail::EmailSendBatchParams.dump_request(params)
+        header_params = {idempotency_key: "idempotency-key"}
+        @client.request(
+          method: :post,
+          path: "emails/batch",
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: ArkEmail::Models::EmailSendBatchResponse,
+          options: 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.
+      #
+      # @overload send_raw(data:, mail_from:, rcpt_to:, request_options: {})
+      #
+      # @param data [String] Base64-encoded RFC 2822 message
+      #
+      # @param mail_from [String] Envelope sender address
+      #
+      # @param rcpt_to [Array<String>] Envelope recipient addresses
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::EmailSendRawResponse]
+      #
+      # @see ArkEmail::Models::EmailSendRawParams
+      def send_raw(params)
+        parsed, options = ArkEmail::EmailSendRawParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "emails/raw",
+          body: parsed,
+          model: ArkEmail::Models::EmailSendRawResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/ark_email/resources/suppressions.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Suppressions
+      # Add an email address to the suppression list. The address will not receive any
+      # emails until removed.
+      #
+      # @overload create(address:, reason: nil, request_options: {})
+      #
+      # @param address [String] Email address to suppress
+      #
+      # @param reason [String] Reason for suppression
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::SuppressionCreateResponse]
+      #
+      # @see ArkEmail::Models::SuppressionCreateParams
+      def create(params)
+        parsed, options = ArkEmail::SuppressionCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "suppressions",
+          body: parsed,
+          model: ArkEmail::Models::SuppressionCreateResponse,
+          options: options
+        )
+      end
+
+      # Check if a specific email address is on the suppression list
+      #
+      # @overload retrieve(email, request_options: {})
+      #
+      # @param email [String] Email address (URL-encoded)
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::SuppressionRetrieveResponse]
+      #
+      # @see ArkEmail::Models::SuppressionRetrieveParams
+      def retrieve(email, params = {})
+        @client.request(
+          method: :get,
+          path: ["suppressions/%1$s", email],
+          model: ArkEmail::Models::SuppressionRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Get all email addresses on the suppression list. These addresses will not
+      # receive any emails.
+      #
+      # @overload list(page: nil, per_page: nil, request_options: {})
+      #
+      # @param page [Integer]
+      # @param per_page [Integer]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Internal::PageNumberPagination<ArkEmail::Models::SuppressionListResponse>]
+      #
+      # @see ArkEmail::Models::SuppressionListParams
+      def list(params = {})
+        parsed, options = ArkEmail::SuppressionListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "suppressions",
+          query: parsed.transform_keys(per_page: "perPage"),
+          page: ArkEmail::Internal::PageNumberPagination,
+          model: ArkEmail::Models::SuppressionListResponse,
+          options: options
+        )
+      end
+
+      # Remove an email address from the suppression list. The address will be able to
+      # receive emails again.
+      #
+      # @overload delete(email, request_options: {})
+      #
+      # @param email [String]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::SuppressionDeleteResponse]
+      #
+      # @see ArkEmail::Models::SuppressionDeleteParams
+      def delete(email, params = {})
+        @client.request(
+          method: :delete,
+          path: ["suppressions/%1$s", email],
+          model: ArkEmail::Models::SuppressionDeleteResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Add up to 1000 email addresses to the suppression list at once
+      #
+      # @overload bulk_create(suppressions:, request_options: {})
+      #
+      # @param suppressions [Array<ArkEmail::Models::SuppressionBulkCreateParams::Suppression>]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::SuppressionBulkCreateResponse]
+      #
+      # @see ArkEmail::Models::SuppressionBulkCreateParams
+      def bulk_create(params)
+        parsed, options = ArkEmail::SuppressionBulkCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "suppressions/bulk",
+          body: parsed,
+          model: ArkEmail::Models::SuppressionBulkCreateResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/ark_email/resources/tracking.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Tracking
+      # Create a new track domain for open/click tracking.
+      #
+      # After creation, you must configure a CNAME record pointing to the provided DNS
+      # value before tracking will work.
+      #
+      # @overload create(domain_id:, name:, ssl_enabled: nil, track_clicks: nil, track_opens: nil, request_options: {})
+      #
+      # @param domain_id [String] ID of the sending domain to attach this track domain to
+      #
+      # @param name [String] Subdomain name (e.g., 'track' for track.yourdomain.com)
+      #
+      # @param ssl_enabled [Boolean] Enable SSL for tracking URLs (recommended)
+      #
+      # @param track_clicks [Boolean] Enable click tracking
+      #
+      # @param track_opens [Boolean] Enable open tracking (tracking pixel)
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TrackingCreateResponse]
+      #
+      # @see ArkEmail::Models::TrackingCreateParams
+      def create(params)
+        parsed, options = ArkEmail::TrackingCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "tracking",
+          body: parsed,
+          model: ArkEmail::Models::TrackingCreateResponse,
+          options: options
+        )
+      end
+
+      # Get details of a specific track domain including DNS configuration
+      #
+      # @overload retrieve(tracking_id, request_options: {})
+      #
+      # @param tracking_id [String] Track domain ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TrackingRetrieveResponse]
+      #
+      # @see ArkEmail::Models::TrackingRetrieveParams
+      def retrieve(tracking_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["tracking/%1$s", tracking_id],
+          model: ArkEmail::Models::TrackingRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Update track domain settings.
+      #
+      # Use this to:
+      #
+      # - Enable/disable click tracking
+      # - Enable/disable open tracking
+      # - Enable/disable SSL
+      # - Set excluded click domains
+      #
+      # @overload update(tracking_id, excluded_click_domains: nil, ssl_enabled: nil, track_clicks: nil, track_opens: nil, request_options: {})
+      #
+      # @param tracking_id [String] Track domain ID or UUID
+      #
+      # @param excluded_click_domains [String] Comma-separated list of domains to exclude from click tracking
+      #
+      # @param ssl_enabled [Boolean] Enable or disable SSL for tracking URLs
+      #
+      # @param track_clicks [Boolean] Enable or disable click tracking
+      #
+      # @param track_opens [Boolean] Enable or disable open tracking
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TrackingUpdateResponse]
+      #
+      # @see ArkEmail::Models::TrackingUpdateParams
+      def update(tracking_id, params = {})
+        parsed, options = ArkEmail::TrackingUpdateParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["tracking/%1$s", tracking_id],
+          body: parsed,
+          model: ArkEmail::Models::TrackingUpdateResponse,
+          options: options
+        )
+      end
+
+      # List all track domains configured for your server. Track domains enable open and
+      # click tracking for your emails.
+      #
+      # @overload list(request_options: {})
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TrackingListResponse]
+      #
+      # @see ArkEmail::Models::TrackingListParams
+      def list(params = {})
+        @client.request(
+          method: :get,
+          path: "tracking",
+          model: ArkEmail::Models::TrackingListResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Delete a track domain. This will disable tracking for any emails using this
+      # domain.
+      #
+      # @overload delete(tracking_id, request_options: {})
+      #
+      # @param tracking_id [String] Track domain ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TrackingDeleteResponse]
+      #
+      # @see ArkEmail::Models::TrackingDeleteParams
+      def delete(tracking_id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["tracking/%1$s", tracking_id],
+          model: ArkEmail::Models::TrackingDeleteResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Check DNS configuration for the track domain.
+      #
+      # The track domain requires a CNAME record to be configured before open and click
+      # tracking will work. Use this endpoint to verify the DNS is correctly set up.
+      #
+      # @overload verify(tracking_id, request_options: {})
+      #
+      # @param tracking_id [String] Track domain ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::TrackingVerifyResponse]
+      #
+      # @see ArkEmail::Models::TrackingVerifyParams
+      def verify(tracking_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["tracking/%1$s/verify", tracking_id],
+          model: ArkEmail::Models::TrackingVerifyResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end