unsent 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95a31fbac0136fab785027f7812e7b3122ea28f79dcda16dd8bcf30782d6a788
-  data.tar.gz: 893a89d9dba0d1ae63f1c96fe62d30b99bee7029cda09aa8d4d88172f3875b53
+  metadata.gz: aa505d7132d95fc8d1d1081eacdc6dc1c152d7265775437c7841a63f0cfbab0b
+  data.tar.gz: d173d3f42bb1b159f2a4d59070d7f1c6db41bb8af2771c29d1808f742541394a
 SHA512:
-  metadata.gz: ee78bacbfaa8d1cafe58412d8fef02d342bc01542e255257c5bc2e73ea1a94d9d2a64bdf89939c786fd0f6d4c30c4ce58a6749118c1181ebb41661fe99bff98c
-  data.tar.gz: 2ea07e0707bc12b3db46e94470521d315df377f35fd6e2b060b10ca9fedb8e38619001abfc5022d78f890f7cb238a4d1f0110e30de26a98783a17c9f5a29dd04
+  metadata.gz: 22ae152f36d21cc5f7dda582594d1b0cb0e667fba6765e9dbf3e14f23e9cf2f65f15f4ff937a09a36303d04d0d4208c5dfd5aa31121bd6c86b759dbc6a40dffd
+  data.tar.gz: 12f06ce781b6c75e5cc7985bd9eaa5dd1f48754715a0115cca022ed3467de14daf716284a373d17a2ea7d8beb7cb5d661b5c8b95ecf5ef0b6be18efd2daec831

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 TODO: Write your name
+Copyright (c) 2025 Sourav Ukil
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -35,7 +35,7 @@ gem install unsent
 ```ruby
 require 'unsent'
 
-client = Unsent::Client.new('us_xxx')
+client = Unsent::Client.new('un_xxx')
 ```
 
 ### Environment Variables
@@ -109,6 +109,21 @@ data, error = client.emails.batch(emails)
 puts "Sent #{data['emails'].length} emails" if data
 ```
 
+#### Idempotent Retries
+
+To prevent duplicate emails when retrying failed requests, you can provide an idempotency key.
+
+```ruby
+data, error = client.emails.send({
+  to: 'user@example.com',
+  from: 'no-reply@yourdomain.com',
+  subject: 'Welcome',
+  html: '<strong>Hello!</strong>'
+}, {
+  idempotency_key: 'unique-key-123'
+})
+```
+
 ### Managing Emails
 
 #### Get Email
@@ -252,7 +267,7 @@ end
 To handle errors as return values instead:
 
 ```ruby
-client = Unsent::Client.new('us_xxx', raise_on_error: false)
+client = Unsent::Client.new('un_xxx', raise_on_error: false)
 
 data, error = client.emails.get('email_123')
 if error
@@ -262,6 +277,262 @@ else
 end
 ```
 
+## Email Management
+
+### List Emails
+
+Retrieve a paginated list of emails with optional filters:
+
+```ruby
+data, error = client.emails.list(
+  page: 1,
+  limit: 10,
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+  domainId: 'domain_123'
+)
+
+# Support for multiple domain IDs
+data, error = client.emails.list(domainId: ['domain_1', 'domain_2'])
+```
+
+### Email Statistics
+
+```ruby
+# Get complaints
+data, error = client.emails.get_complaints(page: 1, limit: 10)
+
+# Get bounces
+data, error = client.emails.get_bounces(page: 1, limit: 10)
+
+# Get unsubscribes
+data, error = client.emails.get_unsubscribes(page: 1, limit: 10)
+```
+
+## Contact Books
+
+Organize your contacts into separate books.
+
+### Create Contact Book
+
+```ruby
+data, error = client.contact_books.create(
+  name: 'Newsletter Subscribers',
+  emoji: '📧'
+)
+```
+
+### List Contact Books
+
+```ruby
+books, error = client.contact_books.list
+books.each { |book| puts book['name'] }
+```
+
+### Get Contact Book
+
+```ruby
+book, error = client.contact_books.get('book_123')
+```
+
+### Update Contact Book
+
+```ruby
+data, error = client.contact_books.update('book_123', name: 'Updated Name')
+```
+
+### Delete Contact Book
+
+```ruby
+data, error = client.contact_books.delete('book_123')
+```
+
+## Contacts
+
+### List Contacts
+
+```ruby
+data, error = client.contacts.list('book_123',
+  page: 1,
+  limit: 10,
+  search: 'john@example.com'
+)
+```
+
+## Campaigns
+
+### List Campaigns
+
+```ruby
+campaigns, error = client.campaigns.list
+```
+
+## Analytics
+
+Get insights into your email sending performance.
+
+### Overall Analytics
+
+```ruby
+data, error = client.analytics.get
+puts "Sent: #{data['sent']}, Delivered: #{data['delivered']}"
+```
+
+### Time Series Data
+
+```ruby
+data, error = client.analytics.get_time_series(
+  days: 30,
+  domain: 'yourdomain.com'
+)
+```
+
+### Reputation Score
+
+```ruby
+data, error = client.analytics.get_reputation(domain: 'yourdomain.com')
+puts "Reputation Score: #{data['score']}"
+```
+
+## Templates
+
+Manage reusable email templates.
+
+### Create Template
+
+```ruby
+data, error = client.templates.create(
+  name: 'Welcome Email',
+  subject: 'Welcome to {{companyName}}!',
+  html: '<h1>Welcome {{firstName}}!</h1>'
+)
+```
+
+### List Templates
+
+```ruby
+templates, error = client.templates.list
+```
+
+### Get Template
+
+```ruby
+template, error = client.templates.get('template_123')
+```
+
+### Update Template
+
+```ruby
+data, error = client.templates.update('template_123',
+  subject: 'Updated Subject'
+)
+```
+
+### Delete Template
+
+```ruby
+data, error = client.templates.delete('template_123')
+```
+
+## Suppressions
+
+Manage your email suppression list.
+
+### List Suppressions
+
+```ruby
+data, error = client.suppressions.list(
+  page: 1,
+  limit: 10,
+  reason: 'MANUAL',
+  search: 'user@'
+)
+```
+
+### Add to Suppression List
+
+```ruby
+data, error = client.suppressions.add(
+  email: 'blocked@example.com',
+  reason: 'MANUAL'
+)
+```
+
+### Remove from Suppression List
+
+```ruby
+data, error = client.suppressions.delete('blocked@example.com')
+```
+
+## API Keys
+
+Manage your API keys programmatically.
+
+### List API Keys
+
+```ruby
+keys, error = client.api_keys.list
+```
+
+### Create API Key
+
+```ruby
+data, error = client.api_keys.create(
+  name: 'Production Key',
+  permission: 'SENDING'
+)
+puts "New key: #{data['key']}"
+```
+
+### Delete API Key
+
+```ruby
+data, error = client.api_keys.delete('key_123')
+```
+
+## Webhooks
+
+> **Note**: Webhooks are currently a future feature and are documented here for reference.
+
+Configure webhooks to receive real-time notifications.
+
+### List Webhooks
+
+```ruby
+webhooks, error = client.webhooks.list
+```
+
+### Create Webhook
+
+```ruby
+data, error = client.webhooks.create(
+  url: 'https://yourdomain.com/webhooks',
+  events: ['email.sent', 'email.delivered', 'email.bounced']
+)
+```
+
+### Update Webhook
+
+```ruby
+data, error = client.webhooks.update('webhook_123',
+  url: 'https://yourdomain.com/updated-webhook'
+)
+```
+
+### Delete Webhook
+
+```ruby
+data, error = client.webhooks.delete('webhook_123')
+```
+
+## Settings
+
+Retrieve account settings.
+
+```ruby
+settings, error = client.settings.get
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.

data/lib/unsent/analytics.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Unsent
+  class Analytics
+    def initialize(client)
+      @client = client
+    end
+
+    def get
+      @client.get('/analytics')
+    end
+
+    def get_time_series(query = {})
+      params = []
+      params << "days=#{query[:days]}" if query[:days]
+      params << "domain=#{query[:domain]}" if query[:domain]
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/analytics/time-series#{query_string}")
+    end
+
+    def get_reputation(query = {})
+      params = []
+      params << "domain=#{query[:domain]}" if query[:domain]
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/analytics/reputation#{query_string}")
+    end
+  end
+end

data/lib/unsent/api_keys.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Unsent
+  class ApiKeys
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      @client.get('/api-keys')
+    end
+
+    def create(payload)
+      @client.post('/api-keys', payload)
+    end
+
+    def delete(id)
+      @client.delete("/api-keys/#{id}")
+    end
+  end
+end

data/lib/unsent/campaigns.rb

@@ -6,6 +6,10 @@ module Unsent
       @client = client
     end
 
+    def list
+      @client.get('/campaigns')
+    end
+
     def create(payload)
       @client.post("/campaigns", payload)
     end

data/lib/unsent/client.rb

@@ -9,7 +9,7 @@ module Unsent
     DEFAULT_BASE_URL = "https://api.unsent.dev"
 
     attr_reader :key, :url, :raise_on_error
-    attr_accessor :emails, :contacts, :campaigns, :domains
+    attr_accessor :emails, :contacts, :campaigns, :domains, :analytics, :api_keys, :contact_books, :settings, :suppressions, :templates, :webhooks
 
     def initialize(key = nil, url: nil, raise_on_error: true)
       @key = key || ENV["UNSENT_API_KEY"] || ENV["UNSENT_API_KEY"]
@@ -24,9 +24,16 @@ module Unsent
       @contacts = Contacts.new(self)
       @campaigns = Campaigns.new(self)
       @domains = Domains.new(self)
+      @analytics = Analytics.new(self)
+      @api_keys = ApiKeys.new(self)
+      @contact_books = ContactBooks.new(self)
+      @settings = Settings.new(self)
+      @suppressions = Suppressions.new(self)
+      @templates = Templates.new(self)
+      @webhooks = Webhooks.new(self)
     end
 
-    def request(method, path, body = nil)
+    def request(method, path, body = nil, headers = {})
       uri = URI("#{@url}#{path}")
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
@@ -42,6 +49,11 @@ module Unsent
 
       request["Authorization"] = "Bearer #{@key}"
       request["Content-Type"] = "application/json"
+      
+      headers.each do |key, value|
+        request[key] = value
+      end
+
       request.body = body.to_json if body
 
       response = http.request(request)
@@ -67,24 +79,24 @@ module Unsent
       end
     end
 
-    def post(path, body)
-      request("POST", path, body)
+    def post(path, body, headers = {})
+      request("POST", path, body, headers)
     end
 
-    def get(path)
-      request("GET", path)
+    def get(path, headers = {})
+      request("GET", path, nil, headers)
     end
 
-    def put(path, body)
-      request("PUT", path, body)
+    def put(path, body, headers = {})
+      request("PUT", path, body, headers)
     end
 
-    def patch(path, body)
-      request("PATCH", path, body)
+    def patch(path, body, headers = {})
+      request("PATCH", path, body, headers)
     end
 
-    def delete(path, body = nil)
-      request("DELETE", path, body)
+    def delete(path, body = nil, headers = {})
+      request("DELETE", path, body, headers)
     end
   end
 end

data/lib/unsent/contact_books.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Unsent
+  class ContactBooks
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      @client.get('/contactBooks')
+    end
+
+    def create(payload)
+      @client.post('/contactBooks', payload)
+    end
+
+    def get(id)
+      @client.get("/contactBooks/#{id}")
+    end
+
+    def update(id, payload)
+      @client.patch("/contactBooks/#{id}", payload)
+    end
+
+    def delete(id)
+      @client.delete("/contactBooks/#{id}")
+    end
+  end
+end

data/lib/unsent/contacts.rb

@@ -6,6 +6,17 @@ module Unsent
       @client = client
     end
 
+    def list(book_id, query = {})
+      params = []
+      params << "emails=#{query[:emails]}" if query[:emails]
+      params << "page=#{query[:page]}" if query[:page]
+      params << "limit=#{query[:limit]}" if query[:limit]
+      params << "ids=#{query[:ids]}" if query[:ids]
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/contactBooks/#{book_id}/contacts#{query_string}")
+    end
+
     def create(book_id, payload)
       @client.post("/contactBooks/#{book_id}/contacts", payload)
     end

data/lib/unsent/emails.rb

@@ -6,11 +6,11 @@ module Unsent
       @client = client
     end
 
-    def send(payload)
-      create(payload)
+    def send(payload, options = {})
+      create(payload, options)
     end
 
-    def create(payload)
+    def create(payload, options = {})
       # Normalize from_ to from
       payload = payload.dup
       payload[:from] = payload.delete(:from_) if payload.key?(:from_) && !payload.key?(:from)
@@ -20,10 +20,13 @@ module Unsent
         payload[:scheduledAt] = payload[:scheduledAt].iso8601
       end
 
-      @client.post("/emails", payload)
+      headers = {}
+      headers["Idempotency-Key"] = options[:idempotency_key] if options[:idempotency_key]
+
+      @client.post("/emails", payload, headers)
     end
 
-    def batch(emails)
+    def batch(emails, options = {})
       items = emails.map do |email|
         email = email.dup
         email[:from] = email.delete(:from_) if email.key?(:from_) && !email.key?(:from)
@@ -31,7 +34,10 @@ module Unsent
         email
       end
 
-      @client.post("/emails/batch", items)
+      headers = {}
+      headers["Idempotency-Key"] = options[:idempotency_key] if options[:idempotency_key]
+
+      @client.post("/emails/batch", items, headers)
     end
 
     def get(email_id)
@@ -47,5 +53,52 @@ module Unsent
     def cancel(email_id)
       @client.post("/emails/#{email_id}/cancel", {})
     end
+
+    def list(query = {})
+      params = []
+      params << "page=#{query[:page]}" if query[:page]
+      params << "limit=#{query[:limit]}" if query[:limit]
+      params << "startDate=#{query[:startDate]}" if query[:startDate]
+      params << "endDate=#{query[:endDate]}" if query[:endDate]
+      
+      # Handle domainId as both string and array
+      if query[:domainId]
+        if query[:domainId].is_a?(Array)
+          query[:domainId].each { |id| params << "domainId=#{id}" }
+        else
+          params << "domainId=#{query[:domainId]}"
+        end
+      end
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/emails#{query_string}")
+    end
+
+    def get_complaints(query = {})
+      params = []
+      params << "page=#{query[:page]}" if query[:page]
+      params << "limit=#{query[:limit]}" if query[:limit]
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/emails/complaints#{query_string}")
+    end
+
+    def get_bounces(query = {})
+      params = []
+      params << "page=#{query[:page]}" if query[:page]
+      params << "limit=#{query[:limit]}" if query[:limit]
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/emails/bounces#{query_string}")
+    end
+
+    def get_unsubscribes(query = {})
+      params = []
+      params << "page=#{query[:page]}" if query[:page]
+      params << "limit=#{query[:limit]}" if query[:limit]
+      
+      query_string = params.empty? ? '' : "?#{params.join('&')}"
+      @client.get("/emails/unsubscribes#{query_string}")
+    end
   end
 end

data/lib/unsent/errors.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Unsent
+  class Error < StandardError; end
+
   class HTTPError < Error
     attr_reader :status_code, :error, :method, :path