vaartix 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: edf789fec70a5e25fc68cca165aa0013a774254b2f0cfbeba8b833e1b51f2e8c
4
+ data.tar.gz: 8a88bdedf68027185a71deeed5a8616c91fa05acc8fe8da1c8aa52d3bf4be184
5
+ SHA512:
6
+ metadata.gz: 660673edbd362f8bba5f201934d505ee5608aaaa9d9feee10913be5c1b15c04ecb2d640543c4bcfdbce78289d51f72e78c62643db2dfacd1d98d4840ede533c2
7
+ data.tar.gz: 3ab847d2430b89b2d265fee2f4d3b42599b363b738cadc0e28dc98895016e8012601ffe88dc8dcac533c1dcd7ef979661f1980a99d9656123f9c3edc8440876c
data/CHANGELOG.md ADDED
@@ -0,0 +1,10 @@
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ ## 0.1.0
6
+
7
+ - First release: send (with idempotency keys, scheduling, tags, attachments and open/click tracking),
8
+ batch send, get, list and cancel emails, update domain tracking defaults, manage webhook
9
+ endpoints and deliveries, and `Vaartix.verify_webhook` (Standard Webhooks; Rails-style headers work),
10
+ including the receiving server's reply (`diagnosticCode`) for delays and bounces.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NAP Designs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,105 @@
1
+ # Vaartix Ruby SDK
2
+
3
+ The official Ruby client for [Vaartix](https://vaartix.com), the transactional email API built in India.
4
+ Data stored in India (AWS Mumbai), pricing in ₹.
5
+
6
+ ```sh
7
+ gem install vaartix
8
+ # or in your Gemfile
9
+ gem "vaartix"
10
+ ```
11
+
12
+ Ruby 3.1 or newer. No dependencies outside the standard library.
13
+
14
+ ## Send an email
15
+
16
+ ```ruby
17
+ require "vaartix"
18
+
19
+ vaartix = Vaartix::Client.new # reads VAARTIX_API_KEY
20
+
21
+ email = vaartix.emails.send(
22
+ from: "Acme <orders@acme.in>", # an address on a domain verified in Vaartix
23
+ to: "priya@example.com",
24
+ subject: "Your order is confirmed",
25
+ html: "<p>Thanks for your order!</p>"
26
+ )
27
+ email["id"] # => "em_..."
28
+ ```
29
+
30
+ Keys can be snake_case (`reply_to`, `scheduled_at`) or the API's camelCase. Responses are the API's JSON as
31
+ hashes. Testing? Send to `delivered@test.vaartix.com` (or `bounced@` / `complained@`); nothing real is sent.
32
+
33
+ ## Errors
34
+
35
+ ```ruby
36
+ begin
37
+ vaartix.emails.send(...)
38
+ rescue Vaartix::Error => e
39
+ e.type # "validation_error", "rate_limit_exceeded", ... or "network_error"
40
+ e.status_code # 422, 429, ... or nil when no response was received
41
+ end
42
+ ```
43
+
44
+ ## More sending options
45
+
46
+ ```ruby
47
+ vaartix.emails.send(email, idempotency_key: "receipt-10482") # safe retries for 24 hours
48
+ vaartix.emails.send(**email, scheduled_at: "2026-11-15T10:00:00+05:30")
49
+ vaartix.batch.send([email_a, email_b]) # up to 100 in one request
50
+ vaartix.emails.send(**email, tracking: { opens: true, clicks: false })
51
+ ```
52
+
53
+ Keep click tracking off for login codes, password resets and magic links.
54
+
55
+ ## Read emails
56
+
57
+ Needs a full-access key.
58
+
59
+ ```ruby
60
+ vaartix.emails.get("em_...") # content, status and events
61
+ vaartix.emails.list(limit: 50) # {"data"=>[...], "hasMore"=>true}
62
+ vaartix.emails.cancel("em_...") # a scheduled email
63
+ ```
64
+
65
+ ## Webhooks
66
+
67
+ Check that a webhook request really came from Vaartix before you trust it. Use the **raw** body.
68
+
69
+ ```ruby
70
+ # Rails
71
+ class VaartixWebhooksController < ActionController::API
72
+ def create
73
+ event = Vaartix.verify_webhook(request.raw_post, request.headers, ENV.fetch("VAARTIX_WEBHOOK_SECRET"))
74
+ if event["type"] == Vaartix::Events::BOUNCED
75
+ reply = event["data"]["details"]["diagnosticCode"] # the receiving server's reply
76
+ end
77
+ head :ok
78
+ rescue Vaartix::WebhookVerificationError
79
+ head :bad_request
80
+ end
81
+ end
82
+ ```
83
+
84
+ Signatures follow the [Standard Webhooks](https://www.standardwebhooks.com) spec. Manage endpoints with
85
+ `vaartix.webhooks.create`, `list`, `get`, `update`, `remove`, `rotate_secret`, `deliveries` and `retry_delivery`.
86
+
87
+ ## Domains
88
+
89
+ ```ruby
90
+ vaartix.domains.update(domain_id, open_tracking: true)
91
+ ```
92
+
93
+ ## Docs
94
+
95
+ - Docs: https://vaartix.com/docs
96
+ - API reference: https://vaartix.com/docs/api
97
+ - Status: https://status.vaartix.com
98
+
99
+ ## Contributing and security
100
+
101
+ Issues and pull requests are welcome. Report security problems privately, see [SECURITY.md](SECURITY.md).
102
+
103
+ ## License
104
+
105
+ MIT
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Vaartix
4
+ VERSION = "0.1.0"
5
+ end
data/lib/vaartix.rb ADDED
@@ -0,0 +1,231 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "net/http"
5
+ require "uri"
6
+ require "openssl"
7
+ require_relative "vaartix/version"
8
+
9
+ # The official Ruby client for Vaartix, the transactional email API built in India.
10
+ #
11
+ # vaartix = Vaartix::Client.new # reads VAARTIX_API_KEY
12
+ # vaartix.emails.send(from: "Acme <orders@acme.in>", to: "priya@example.com",
13
+ # subject: "Your order is confirmed", html: "<p>Thanks!</p>")
14
+ # # => {"id"=>"em_..."}
15
+ module Vaartix
16
+ DEFAULT_BASE_URL = "https://api.vaartix.com"
17
+
18
+ # The API answered with an error, or the request could not be made.
19
+ class Error < StandardError
20
+ # The API's error type, e.g. "validation_error", or "network_error".
21
+ attr_reader :type
22
+ # The HTTP status, or nil when no response was received.
23
+ attr_reader :status_code
24
+
25
+ def initialize(type, message, status_code = nil)
26
+ super(message)
27
+ @type = type
28
+ @status_code = status_code
29
+ end
30
+ end
31
+
32
+ # A webhook request's signature, timestamp or body is not valid.
33
+ class WebhookVerificationError < StandardError; end
34
+
35
+ # snake_case keys you pass become the API's camelCase (reply_to -> replyTo).
36
+ KEY_NAMES = {
37
+ reply_to: :replyTo, scheduled_at: :scheduledAt, content_type: :contentType, content_id: :contentId,
38
+ open_tracking: :openTracking, click_tracking: :clickTracking
39
+ }.freeze
40
+
41
+ def self.to_api(value)
42
+ case value
43
+ when Hash then value.each_with_object({}) { |(k, v), h| h[KEY_NAMES.fetch(k.to_sym, k)] = to_api(v) unless v.nil? }
44
+ when Array then value.map { |v| to_api(v) }
45
+ else value
46
+ end
47
+ end
48
+
49
+ # Thread-safe client. Create one and reuse it.
50
+ class Client
51
+ attr_reader :emails, :batch, :domains, :webhooks
52
+
53
+ # http: optional callable(method, url, headers, body) -> [status, body], for tests or custom transports.
54
+ def initialize(api_key = nil, base_url: DEFAULT_BASE_URL, timeout: 30, http: nil)
55
+ @api_key = api_key || ENV.fetch("VAARTIX_API_KEY", nil)
56
+ if @api_key.nil? || @api_key.empty?
57
+ raise ArgumentError, "Missing API key. Pass it to Vaartix::Client.new(\"vx_...\") or set VAARTIX_API_KEY."
58
+ end
59
+
60
+ @base_url = base_url.sub(%r{/+\z}, "")
61
+ @timeout = timeout
62
+ @http = http || method(:net_http)
63
+ @emails = Emails.new(self)
64
+ @batch = Batch.new(self)
65
+ @domains = Domains.new(self)
66
+ @webhooks = Webhooks.new(self)
67
+ end
68
+
69
+ # @api private
70
+ def request(method, path, body = nil, idempotency_key: nil)
71
+ headers = {
72
+ "Authorization" => "Bearer #{@api_key}",
73
+ "User-Agent" => "vaartix-ruby/#{VERSION}",
74
+ "Accept" => "application/json"
75
+ }
76
+ headers["Content-Type"] = "application/json" unless body.nil?
77
+ headers["Idempotency-Key"] = idempotency_key if idempotency_key
78
+ payload = body.nil? ? nil : JSON.generate(Vaartix.to_api(body))
79
+ begin
80
+ status, raw = @http.call(method, "#{@base_url}#{path}", headers, payload)
81
+ rescue StandardError => e
82
+ raise Error.new("network_error", e.message)
83
+ end
84
+ parsed = begin
85
+ raw.nil? || raw.empty? ? nil : JSON.parse(raw)
86
+ rescue JSON::ParserError
87
+ nil
88
+ end
89
+ return parsed if status.between?(200, 299)
90
+
91
+ err = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : {}
92
+ raise Error.new(err["type"] || "api_error", err["message"] || "Request failed with status #{status}", status)
93
+ end
94
+
95
+ def self.escape(id) = URI.encode_www_form_component(id.to_s).gsub("+", "%20")
96
+
97
+ private
98
+
99
+ def net_http(method, url, headers, body)
100
+ uri = URI(url)
101
+ klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete }.fetch(method)
102
+ req = klass.new(uri)
103
+ headers.each { |k, v| req[k] = v }
104
+ req.body = body if body
105
+ res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |h|
106
+ h.request(req)
107
+ end
108
+ [res.code.to_i, res.body]
109
+ end
110
+ end
111
+
112
+ # Send and read emails.
113
+ class Emails
114
+ def initialize(client) = @client = client
115
+
116
+ # Send one email. Keys can be snake_case (reply_to, scheduled_at) or camelCase.
117
+ # tracking: { opens: true, clicks: false } overrides the domain's defaults.
118
+ # Pass a hash, or the fields as keywords: emails.send(from: ..., to: ..., subject: ..., html: ...).
119
+ def send(email = nil, idempotency_key: nil, **fields)
120
+ @client.request(:post, "/emails", email || fields, idempotency_key: idempotency_key)
121
+ end
122
+
123
+ # One email with its events. Needs a full-access key.
124
+ def get(id) = @client.request(:get, "/emails/#{Client.escape(id)}")
125
+
126
+ # Recent emails, newest first. Needs a full-access key.
127
+ def list(limit: nil, before: nil)
128
+ query = URI.encode_www_form({ limit: limit, before: before }.compact)
129
+ @client.request(:get, "/emails#{query.empty? ? "" : "?#{query}"}")
130
+ end
131
+
132
+ # Cancel a scheduled email before it is sent. Needs a full-access key.
133
+ def cancel(id) = @client.request(:post, "/emails/#{Client.escape(id)}/cancel")
134
+ end
135
+
136
+ # Send many emails in one request.
137
+ class Batch
138
+ def initialize(client) = @client = client
139
+
140
+ # Up to 100 emails (no attachments or scheduling). All or nothing. Returns the list of {"id"=>...}.
141
+ def send(emails) = @client.request(:post, "/emails/batch", emails)["data"]
142
+ end
143
+
144
+ # Sending domains. Changes need a full-access key from an owner or admin.
145
+ class Domains
146
+ def initialize(client) = @client = client
147
+
148
+ # Change a domain's default open and click tracking. Keys left out keep their value.
149
+ def update(id, open_tracking: nil, click_tracking: nil)
150
+ @client.request(:patch, "/domains/#{Client.escape(id)}", { open_tracking: open_tracking, click_tracking: click_tracking })
151
+ end
152
+ end
153
+
154
+ # Webhook endpoints. Needs a full-access key.
155
+ class Webhooks
156
+ def initialize(client) = @client = client
157
+
158
+ # Create an endpoint. The response includes the signing secret, shown only this once.
159
+ def create(url:, events:) = @client.request(:post, "/webhooks", { url: url, events: events })
160
+ def list = @client.request(:get, "/webhooks")["data"]
161
+ def get(id) = @client.request(:get, "/webhooks/#{Client.escape(id)}")
162
+
163
+ # Change the URL or events, or turn the endpoint off (status: "disabled") and on.
164
+ def update(id, url: nil, events: nil, status: nil)
165
+ @client.request(:patch, "/webhooks/#{Client.escape(id)}", { url: url, events: events, status: status })
166
+ end
167
+
168
+ def remove(id) = @client.request(:delete, "/webhooks/#{Client.escape(id)}")
169
+
170
+ # Replace the signing secret. The old one stops working immediately.
171
+ def rotate_secret(id) = @client.request(:post, "/webhooks/#{Client.escape(id)}/rotate-secret")
172
+
173
+ # Recent deliveries, newest first.
174
+ def deliveries(id, limit: nil)
175
+ @client.request(:get, "/webhooks/#{Client.escape(id)}/deliveries#{limit ? "?limit=#{Integer(limit)}" : ""}")["data"]
176
+ end
177
+
178
+ # Send a delivery again, with the same webhook-id.
179
+ def retry_delivery(id, delivery_id)
180
+ @client.request(:post, "/webhooks/#{Client.escape(id)}/deliveries/#{Client.escape(delivery_id)}/retry")
181
+ end
182
+ end
183
+
184
+ # Webhook event types.
185
+ module Events
186
+ SENT = "email.sent"
187
+ DELIVERED = "email.delivered"
188
+ DELIVERY_DELAYED = "email.delivery_delayed"
189
+ BOUNCED = "email.bounced"
190
+ COMPLAINED = "email.complained"
191
+ REJECTED = "email.rejected"
192
+ RENDERING_FAILURE = "email.rendering_failure"
193
+ SUPPRESSED = "email.suppressed"
194
+ OPENED = "email.opened"
195
+ CLICKED = "email.clicked"
196
+ ALL = [SENT, DELIVERED, DELIVERY_DELAYED, BOUNCED, COMPLAINED, REJECTED, RENDERING_FAILURE, SUPPRESSED, OPENED,
197
+ CLICKED].freeze
198
+ end
199
+
200
+ # Check that a webhook request really came from Vaartix (Standard Webhooks) and return its parsed body.
201
+ # payload must be the raw body (request.raw_post in Rails). headers: any case, e.g. request.headers.
202
+ # Delays and bounces carry the receiving server's reply in data.details.diagnosticCode.
203
+ def self.verify_webhook(payload, headers, secret, tolerance: 300, now: Time.now.to_i)
204
+ get = ->(name) { headers[name] || headers.find { |k, _| k.to_s.downcase.tr("_", "-").sub(/\Ahttp-/, "") == name }&.last }
205
+ id = get.("webhook-id")
206
+ timestamp = get.("webhook-timestamp")
207
+ signatures = get.("webhook-signature")
208
+ raise WebhookVerificationError, "Missing webhook-id, webhook-timestamp or webhook-signature header." unless id && timestamp && signatures
209
+
210
+ sent = Integer(timestamp, exception: false)
211
+ raise WebhookVerificationError, "The webhook timestamp is too old or in the future." if sent.nil? || (now - sent).abs > tolerance
212
+ raise WebhookVerificationError, "The secret should start with whsec_." unless secret.to_s.start_with?("whsec_")
213
+
214
+ key = secret.delete_prefix("whsec_").unpack1("m0")
215
+ expected = OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{payload}")
216
+ valid = signatures.split(" ").any? do |entry|
217
+ version, signature = entry.split(",", 2)
218
+ next false unless version == "v1" && signature
219
+
220
+ given = signature.unpack1("m")
221
+ given.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(given, expected)
222
+ end
223
+ raise WebhookVerificationError, "The webhook signature does not match." unless valid
224
+
225
+ JSON.parse(payload)
226
+ rescue ArgumentError
227
+ raise WebhookVerificationError, "The secret is not valid base64."
228
+ rescue JSON::ParserError
229
+ raise WebhookVerificationError, "The body is not valid JSON."
230
+ end
231
+ end
metadata ADDED
@@ -0,0 +1,53 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: vaartix
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Vaartix
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description:
14
+ email:
15
+ - support@vaartix.com
16
+ executables: []
17
+ extensions: []
18
+ extra_rdoc_files: []
19
+ files:
20
+ - CHANGELOG.md
21
+ - LICENSE
22
+ - README.md
23
+ - lib/vaartix.rb
24
+ - lib/vaartix/version.rb
25
+ homepage: https://vaartix.com
26
+ licenses:
27
+ - MIT
28
+ metadata:
29
+ source_code_uri: https://github.com/vaartix-mail/vaartix-ruby
30
+ changelog_uri: https://github.com/vaartix-mail/vaartix-ruby/blob/main/CHANGELOG.md
31
+ documentation_uri: https://vaartix.com/docs
32
+ rubygems_mfa_required: 'true'
33
+ post_install_message:
34
+ rdoc_options: []
35
+ require_paths:
36
+ - lib
37
+ required_ruby_version: !ruby/object:Gem::Requirement
38
+ requirements:
39
+ - - ">="
40
+ - !ruby/object:Gem::Version
41
+ version: '3.1'
42
+ required_rubygems_version: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - ">="
45
+ - !ruby/object:Gem::Version
46
+ version: '0'
47
+ requirements: []
48
+ rubygems_version: 3.5.22
49
+ signing_key:
50
+ specification_version: 4
51
+ summary: The official Ruby client for Vaartix, the transactional email API built in
52
+ India.
53
+ test_files: []