transmitly 1.0.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: 42da1a30e16acb855b23bf9c052b115bf63c02e8079961aab49df8f68a732613
4
+ data.tar.gz: 901c5824d00e8fee53ff60ae22286d65d71416807ce2ec2c7281c937c9bae0d5
5
+ SHA512:
6
+ metadata.gz: fd98eb35dc99efdff09efdb16b6703f037e2a8b5957e1e8e124f840e9b41b884008264452dbb98aabd6920be61a1aa4731a51b5c8eed94de400dcf228fa6b447
7
+ data.tar.gz: 7aba3029d774d5345bd328ab1713f91b1a5668a6b4649759b7cf776d718af54ab4f2c2cc9828a9ea5fc35b37045457550818cf818dec0c7c2de290987b4d588e
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Swift Nodes LLC
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
+ # Transmitly Ruby SDK
2
+
3
+ Dependency-free Ruby client for the Transmitly API. Requires Ruby 3.0+.
4
+
5
+ ```ruby
6
+ require "transmitly"
7
+
8
+ tx = Transmitly::Client.new(api_key: ENV.fetch("TRANSMITLY_API_KEY"))
9
+
10
+ accepted = tx.emails.deliver(
11
+ from: "Notify <notify@mail.acme.com>",
12
+ to: ["ada@example.net"],
13
+ subject: "Your workspace is ready",
14
+ html: "<p>Welcome.</p>",
15
+ reply_to: "Support <support@acme.com>",
16
+ tags: { flow: "onboarding" }
17
+ )
18
+ # => {"id"=>"msg_…", "status"=>"accepted", "recipients"=>1}
19
+ ```
20
+
21
+ `emails.deliver` generates an idempotency key. Pass `idempotency_key:` to
22
+ control it yourself; retries with the same key return the original message.
23
+
24
+ ## Rails
25
+
26
+ Put the key in credentials and create one client:
27
+
28
+ ```ruby
29
+ # config/initializers/transmitly.rb
30
+ TRANSMITLY = Transmitly::Client.new(
31
+ api_key: Rails.application.credentials.transmitly_api_key!
32
+ )
33
+ ```
34
+
35
+ ```ruby
36
+ # app/controllers/welcome_controller.rb
37
+ TRANSMITLY.emails.deliver(
38
+ from: "Notify <notify@mail.acme.com>",
39
+ to: [current_user.email],
40
+ subject: "Welcome to Acme",
41
+ html: render_to_string(template: "welcome/email", formats: [:html])
42
+ )
43
+ ```
44
+
45
+ Keep the key server-side. In Rails, prefer a background job for the network call
46
+ so the request does not wait on email delivery.
47
+
48
+ ## Resources
49
+
50
+ ```ruby
51
+ tx.messages.list(status: "bounced", limit: 20)
52
+ tx.messages.deliveries(message_id)
53
+ tx.domains.list
54
+ tx.domains.create("mail.acme.com")
55
+ tx.domains.verify(domain_id)
56
+ tx.suppressions.list
57
+ tx.suppressions.add(email: "bounce@example.net", reason: "manual")
58
+ tx.webhooks.list
59
+ tx.webhooks.create(url: "https://api.acme.com/hooks", events: ["email.delivered_to_mx"])
60
+ tx.inbound.routes
61
+ tx.usage.get
62
+ tx.events.list(limit: 50)
63
+ tx.health
64
+ ```
65
+
66
+ Attachments accept base64 content or a public HTTPS path:
67
+
68
+ ```ruby
69
+ tx.emails.deliver(
70
+ from: "Notify <notify@mail.acme.com>",
71
+ to: ["ada@example.net"],
72
+ subject: "November invoice",
73
+ html: "<p>Attached.</p>",
74
+ attachments: [
75
+ { filename: "invoice.pdf", path: "https://cdn.acme.com/invoice.pdf", content_type: "application/pdf" }
76
+ ]
77
+ )
78
+ ```
79
+
80
+ ## Webhooks
81
+
82
+ Verify the raw request body before parsing it:
83
+
84
+ ```ruby
85
+ # app/controllers/webhooks_controller.rb
86
+ def create
87
+ raw = request.raw_post
88
+ unless Transmitly::Client.verify_webhook(raw, request.headers["Transmitly-Signature"], ENV.fetch("TRANSMITLY_WEBHOOK_SECRET"))
89
+ return head :bad_request
90
+ end
91
+
92
+ event = JSON.parse(raw)
93
+ # handle event["type"]
94
+ head :ok
95
+ end
96
+ ```
97
+
98
+ Non-2xx responses raise `Transmitly::Error` with `status`, `code`, `message`
99
+ and `details`. Domain, webhook and inbound management require an API key with
100
+ the `admin` scope.
101
+
102
+ ```bash
103
+ gem build transmitly.gemspec
104
+ gem install ./transmitly-1.0.0.gem
105
+ ```
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Transmitly
4
+ VERSION = "1.0.0"
5
+ end
data/lib/transmitly.rb ADDED
@@ -0,0 +1,291 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "net/http"
5
+ require "openssl"
6
+ require "securerandom"
7
+ require "uri"
8
+
9
+ require_relative "transmitly/version"
10
+
11
+ module Transmitly
12
+ class Error < StandardError
13
+ attr_reader :status, :code, :details
14
+
15
+ def initialize(status:, code: nil, message: nil, details: nil)
16
+ super(message || "Request failed (#{status})")
17
+ @status = status
18
+ @code = code
19
+ @details = details
20
+ end
21
+ end
22
+
23
+ # Raised when a response cannot be decoded as JSON.
24
+ class DecodeError < Error; end
25
+
26
+ # Dependency-free client for the Transmitly email API.
27
+ #
28
+ # tx = Transmitly::Client.new(api_key: ENV.fetch("TRANSMITLY_API_KEY"))
29
+ # accepted = tx.emails.deliver(
30
+ # from: "Notify <notify@mail.acme.com>",
31
+ # to: ["ada@example.net"],
32
+ # subject: "Welcome",
33
+ # html: "<p>Your workspace is ready.</p>"
34
+ # )
35
+ class Client
36
+ DEFAULT_BASE_URL = "https://transmitly.io"
37
+ DEFAULT_TIMEOUT = 15
38
+
39
+ attr_reader :base_url, :timeout, :emails, :messages, :domains, :suppressions,
40
+ :webhooks, :inbound, :usage, :events
41
+
42
+ def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
43
+ raise ArgumentError, "api_key is required" if api_key.nil? || api_key.to_s.empty?
44
+
45
+ @api_key = api_key.to_s
46
+ @base_url = base_url.to_s.sub(%r{/+\z}, "")
47
+ @timeout = timeout
48
+
49
+ @emails = Emails.new(self)
50
+ @messages = Messages.new(self)
51
+ @domains = Domains.new(self)
52
+ @suppressions = Suppressions.new(self)
53
+ @webhooks = Webhooks.new(self)
54
+ @inbound = Inbound.new(self)
55
+ @usage = Usage.new(self)
56
+ @events = Events.new(self)
57
+ end
58
+
59
+ def send_email(payload, idempotency_key: nil)
60
+ emails.deliver(payload, idempotency_key: idempotency_key)
61
+ end
62
+
63
+ def health
64
+ request(:get, "/v1/health", auth: false)
65
+ end
66
+
67
+ # Verify a webhook delivery. Pass the raw request body (not a parsed hash),
68
+ # the Transmitly-Signature header and the endpoint signing secret.
69
+ def self.verify_webhook(raw_body, signature_header, secret, tolerance: 300)
70
+ return false if signature_header.nil? || signature_header.empty?
71
+
72
+ timestamp = nil
73
+ signature = nil
74
+ signature_header.split(",").each do |part|
75
+ key, value = part.strip.split("=", 2)
76
+ next if value.nil?
77
+
78
+ timestamp = value.to_i if key == "t"
79
+ signature = value if key == "v1"
80
+ end
81
+ return false unless timestamp && signature
82
+
83
+ if tolerance.positive? && (Time.now.to_i - timestamp).abs > tolerance
84
+ return false
85
+ end
86
+
87
+ expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, "#{timestamp}.#{raw_body}")
88
+ self.secure_compare(signature, expected)
89
+ end
90
+
91
+ def self.secure_compare(left, right)
92
+ return false unless left.bytesize == right.bytesize
93
+
94
+ result = 0
95
+ left.bytes.zip(right.bytes) { |a, b| result |= a ^ b }
96
+ result.zero?
97
+ end
98
+
99
+ # @api private
100
+ def request(method, path, body: nil, query: nil, headers: {}, auth: true)
101
+ uri = URI.parse("#{@base_url}#{path}")
102
+ if query
103
+ clean = query.each_with_object({}) do |(key, value), out|
104
+ out[key] = value unless value.nil? || value == ""
105
+ end
106
+ uri.query = URI.encode_www_form(clean) unless clean.empty?
107
+ end
108
+
109
+ request_class = case method
110
+ when :get then Net::HTTP::Get
111
+ when :post then Net::HTTP::Post
112
+ when :patch then Net::HTTP::Patch
113
+ when :put then Net::HTTP::Put
114
+ when :delete then Net::HTTP::Delete
115
+ else raise ArgumentError, "unsupported method: #{method}"
116
+ end
117
+
118
+ req = request_class.new(uri.request_uri)
119
+ req["Accept"] = "application/json"
120
+ req["Authorization"] = "Bearer #{@api_key}" if auth
121
+ if body
122
+ req["Content-Type"] = "application/json"
123
+ req.body = JSON.generate(body)
124
+ end
125
+ headers.each { |key, value| req[key] = value }
126
+
127
+ http = Net::HTTP.new(uri.host, uri.port)
128
+ http.use_ssl = uri.scheme == "https"
129
+ http.open_timeout = @timeout
130
+ http.read_timeout = @timeout
131
+ http.write_timeout = @timeout
132
+
133
+ response = http.request(req)
134
+ parse(response)
135
+ end
136
+
137
+ private
138
+
139
+ def parse(response)
140
+ raw = response.body.to_s
141
+ payload =
142
+ if raw.empty?
143
+ nil
144
+ else
145
+ begin
146
+ JSON.parse(raw)
147
+ rescue JSON::ParserError
148
+ raise DecodeError.new(status: response.code.to_i, message: "Could not decode JSON response")
149
+ end
150
+ end
151
+
152
+ return payload if response.is_a?(Net::HTTPSuccess)
153
+
154
+ error = payload.is_a?(Hash) ? payload["error"] || {} : {}
155
+ raise Error.new(
156
+ status: response.code.to_i,
157
+ code: error["code"],
158
+ message: error["message"] || "Request failed (#{response.code})",
159
+ details: error["details"]
160
+ )
161
+ end
162
+
163
+ class Resource
164
+ def initialize(client)
165
+ @client = client
166
+ end
167
+
168
+ private
169
+
170
+ def clean(hash)
171
+ hash.each_with_object({}) do |(key, value), out|
172
+ out[key] = value unless value.nil?
173
+ end
174
+ end
175
+
176
+ def encode(id)
177
+ URI.encode_www_form_component(id.to_s)
178
+ end
179
+ end
180
+
181
+ class Emails < Resource
182
+ def deliver(payload, idempotency_key: nil)
183
+ raise ArgumentError, "from is required" if payload[:from].nil? || payload[:from].to_s.empty?
184
+ raise ArgumentError, "to is required" if payload[:to].nil? || Array(payload[:to]).empty?
185
+ raise ArgumentError, "subject is required" if payload[:subject].nil? || payload[:subject].to_s.empty?
186
+ unless payload[:html] || payload[:text] || payload[:template_id]
187
+ raise ArgumentError, "html, text or template_id is required"
188
+ end
189
+
190
+ key = idempotency_key || SecureRandom.uuid
191
+ @client.request(
192
+ :post,
193
+ "/v1/emails",
194
+ body: clean(payload),
195
+ headers: { "Idempotency-Key" => key }
196
+ )
197
+ end
198
+ alias send_email deliver
199
+
200
+ def get(id)
201
+ @client.request(:get, "/v1/emails/#{encode(id)}")
202
+ end
203
+ end
204
+
205
+ class Messages < Resource
206
+ def list(**params)
207
+ @client.request(:get, "/v1/messages", query: clean(params))
208
+ end
209
+
210
+ def get(id)
211
+ @client.request(:get, "/v1/messages/#{encode(id)}")
212
+ end
213
+
214
+ def deliveries(id)
215
+ @client.request(:get, "/v1/messages/#{encode(id)}/deliveries")
216
+ end
217
+ end
218
+
219
+ class Domains < Resource
220
+ def list
221
+ @client.request(:get, "/v1/domains")
222
+ end
223
+
224
+ def create(domain)
225
+ @client.request(:post, "/v1/domains", body: { domain: domain })
226
+ end
227
+
228
+ def verify(id)
229
+ @client.request(:post, "/v1/domains/#{encode(id)}/verify", body: {})
230
+ end
231
+
232
+ def remove(id)
233
+ @client.request(:delete, "/v1/domains/#{encode(id)}")
234
+ end
235
+ end
236
+
237
+ class Suppressions < Resource
238
+ def list(**params)
239
+ @client.request(:get, "/v1/suppressions", query: clean(params))
240
+ end
241
+
242
+ def add(**input)
243
+ @client.request(:post, "/v1/suppressions", body: clean(input))
244
+ end
245
+
246
+ def remove(id)
247
+ @client.request(:delete, "/v1/suppressions/#{encode(id)}")
248
+ end
249
+ end
250
+
251
+ class Webhooks < Resource
252
+ def list
253
+ @client.request(:get, "/v1/webhooks")
254
+ end
255
+
256
+ def create(**input)
257
+ @client.request(:post, "/v1/webhooks", body: clean(input))
258
+ end
259
+
260
+ def remove(id)
261
+ @client.request(:delete, "/v1/webhooks/#{encode(id)}")
262
+ end
263
+ end
264
+
265
+ class Inbound < Resource
266
+ def routes
267
+ @client.request(:get, "/v1/inbound/routes")
268
+ end
269
+
270
+ def add_route(**input)
271
+ @client.request(:post, "/v1/inbound/routes", body: clean(input))
272
+ end
273
+
274
+ def remove_route(id)
275
+ @client.request(:delete, "/v1/inbound/routes/#{encode(id)}")
276
+ end
277
+ end
278
+
279
+ class Usage < Resource
280
+ def get(**params)
281
+ @client.request(:get, "/v1/usage", query: clean(params))
282
+ end
283
+ end
284
+
285
+ class Events < Resource
286
+ def list(**params)
287
+ @client.request(:get, "/v1/events", query: clean(params))
288
+ end
289
+ end
290
+ end
291
+ end
metadata ADDED
@@ -0,0 +1,80 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: transmitly
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0
5
+ platform: ruby
6
+ authors:
7
+ - Swift Nodes LLC
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: minitest
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - ">="
18
+ - !ruby/object:Gem::Version
19
+ version: '5.0'
20
+ type: :development
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - ">="
25
+ - !ruby/object:Gem::Version
26
+ version: '5.0'
27
+ - !ruby/object:Gem::Dependency
28
+ name: rake
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - ">="
32
+ - !ruby/object:Gem::Version
33
+ version: '13.0'
34
+ type: :development
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - ">="
39
+ - !ruby/object:Gem::Version
40
+ version: '13.0'
41
+ description: Dependency-free Ruby client for sending transactional email and inspecting
42
+ delivery state with Transmitly.
43
+ email:
44
+ - support@transmitly.io
45
+ executables: []
46
+ extensions: []
47
+ extra_rdoc_files: []
48
+ files:
49
+ - LICENSE
50
+ - README.md
51
+ - lib/transmitly.rb
52
+ - lib/transmitly/version.rb
53
+ homepage: https://transmitly.io/docs/sdks
54
+ licenses:
55
+ - MIT
56
+ metadata:
57
+ homepage_uri: https://transmitly.io/docs/sdks
58
+ source_code_uri: https://github.com/Transmitly-io/sdk-ruby
59
+ changelog_uri: https://github.com/Transmitly-io/sdk-ruby/releases
60
+ rubygems_mfa_required: 'true'
61
+ post_install_message:
62
+ rdoc_options: []
63
+ require_paths:
64
+ - lib
65
+ required_ruby_version: !ruby/object:Gem::Requirement
66
+ requirements:
67
+ - - ">="
68
+ - !ruby/object:Gem::Version
69
+ version: '3.0'
70
+ required_rubygems_version: !ruby/object:Gem::Requirement
71
+ requirements:
72
+ - - ">="
73
+ - !ruby/object:Gem::Version
74
+ version: '0'
75
+ requirements: []
76
+ rubygems_version: 3.5.22
77
+ signing_key:
78
+ specification_version: 4
79
+ summary: Ruby client for the Transmitly email API
80
+ test_files: []