sendio 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.
Files changed (47) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +31 -0
  3. data/LICENSE +22 -0
  4. data/NOTICE +1 -0
  5. data/README.md +210 -0
  6. data/app/controllers/action_mailbox/ingresses/sendio/inbound_emails_controller.rb +95 -0
  7. data/lib/sendio/action_mailbox/engine.rb +19 -0
  8. data/lib/sendio/action_mailbox/message_builder.rb +162 -0
  9. data/lib/sendio/action_mailbox.rb +5 -0
  10. data/lib/sendio/api_keys.rb +32 -0
  11. data/lib/sendio/automations/runs.rb +22 -0
  12. data/lib/sendio/automations/templates.rb +29 -0
  13. data/lib/sendio/automations.rb +64 -0
  14. data/lib/sendio/batch.rb +36 -0
  15. data/lib/sendio/broadcasts.rb +180 -0
  16. data/lib/sendio/client.rb +19 -0
  17. data/lib/sendio/contact_properties.rb +106 -0
  18. data/lib/sendio/contacts/imports.rb +64 -0
  19. data/lib/sendio/contacts/segments.rb +66 -0
  20. data/lib/sendio/contacts/topics.rb +80 -0
  21. data/lib/sendio/contacts.rb +131 -0
  22. data/lib/sendio/domains.rb +60 -0
  23. data/lib/sendio/emails/attachments.rb +67 -0
  24. data/lib/sendio/emails/receiving/attachments.rb +69 -0
  25. data/lib/sendio/emails/receiving.rb +51 -0
  26. data/lib/sendio/emails.rb +124 -0
  27. data/lib/sendio/errors.rb +59 -0
  28. data/lib/sendio/events.rb +46 -0
  29. data/lib/sendio/logs.rb +20 -0
  30. data/lib/sendio/mailboxes.rb +87 -0
  31. data/lib/sendio/mailer.rb +241 -0
  32. data/lib/sendio/multipart_request.rb +67 -0
  33. data/lib/sendio/oauth_grants.rb +20 -0
  34. data/lib/sendio/pagination_helper.rb +30 -0
  35. data/lib/sendio/railtie.rb +14 -0
  36. data/lib/sendio/request.rb +122 -0
  37. data/lib/sendio/response.rb +154 -0
  38. data/lib/sendio/segments.rb +38 -0
  39. data/lib/sendio/suppressions/batch.rb +44 -0
  40. data/lib/sendio/suppressions.rb +64 -0
  41. data/lib/sendio/templates.rb +50 -0
  42. data/lib/sendio/topics.rb +38 -0
  43. data/lib/sendio/usage.rb +14 -0
  44. data/lib/sendio/version.rb +5 -0
  45. data/lib/sendio/webhooks.rb +329 -0
  46. data/lib/sendio.rb +78 -0
  47. metadata +119 -0
@@ -0,0 +1,64 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ # automations api wrapper
5
+ module Automations
6
+ class << self
7
+ # https://developer.send.io/docs/api
8
+ def create(params = {})
9
+ Sendio::Request.new("automations", params, "post").perform
10
+ end
11
+
12
+ # https://developer.send.io/docs/api
13
+ def get(automation_id = "")
14
+ Sendio::Request.new("automations/#{automation_id}", {}, "get").perform
15
+ end
16
+
17
+ # https://developer.send.io/docs/api
18
+ def update(params = {})
19
+ path = "automations/#{params[:automation_id]}"
20
+ payload = params.reject { |k, _| k == :automation_id }
21
+ Sendio::Request.new(path, payload, "patch").perform
22
+ end
23
+
24
+ # https://developer.send.io/docs/api
25
+ def remove(automation_id = "")
26
+ Sendio::Request.new("automations/#{automation_id}", {}, "delete").perform
27
+ end
28
+
29
+ # https://developer.send.io/docs/api
30
+ def duplicate(automation_id = "")
31
+ Sendio::Request.new("automations/#{automation_id}/duplicate", {}, "post").perform
32
+ end
33
+
34
+ # https://developer.send.io/docs/api
35
+ def stop(automation_id = "")
36
+ Sendio::Request.new("automations/#{automation_id}/stop", {}, "post").perform
37
+ end
38
+
39
+ # Create a disabled automation from an automation template.
40
+ # see more: https://developer.send.io/docs/api
41
+ #
42
+ # @param params [Hash] :slug and :sender ({ from:, reply_to: }) are required; :topic_id is
43
+ # required for marketing templates. Optional :version, :name, :events
44
+ # ({ ref => { mode: "create" | "existing", name: } }) and :params ({ ref => value }).
45
+ # @param options [Hash] Additional options for the request
46
+ # @option options [String] :idempotency_key Optional idempotency key
47
+ #
48
+ # @example
49
+ # Sendio::Automations.create_from_template(
50
+ # { slug: "welcome-series", sender: { from: "Acme <hi@acme.com>" }, topic_id: "topic_123" },
51
+ # options: { idempotency_key: "welcome-1" }
52
+ # )
53
+ def create_from_template(params, options: {})
54
+ Sendio::Request.new("automations/from-template", params, "post", options: options).perform
55
+ end
56
+
57
+ # https://developer.send.io/docs/api
58
+ def list(params = {})
59
+ path = Sendio::PaginationHelper.build_paginated_path("automations", params)
60
+ Sendio::Request.new(path, {}, "get").perform
61
+ end
62
+ end
63
+ end
64
+ end
@@ -0,0 +1,36 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ # Module responsible for wrapping Batch email sending API
5
+ module Batch
6
+ class << self
7
+ # Send a batch of emails
8
+ #
9
+ # @param params [Array<Hash>] Array of email parameters (max 100 emails)
10
+ # @param options [Hash] Additional options for the request
11
+ # @option options [String] :idempotency_key Optional idempotency key
12
+ # @option options [String] :batch_validation Batch validation mode: "strict" (default) or "permissive"
13
+ # - "strict": Entire batch fails if any email is invalid
14
+ # - "permissive": Sends valid emails and returns errors for invalid ones
15
+ #
16
+ # @return [Hash] Response with :data array and optional :errors array (in permissive mode)
17
+ #
18
+ # @example Send batch with strict validation (default)
19
+ # Sendio::Batch.send([
20
+ # { from: "sender@example.com", to: ["recipient@example.com"], subject: "Hello", html: "<p>Hi</p>" }
21
+ # ])
22
+ #
23
+ # @example Send batch with permissive validation
24
+ # response = Sendio::Batch.send(emails, options: { batch_validation: "permissive" })
25
+ # # response[:data] contains successful email IDs
26
+ # # response[:errors] contains validation errors with index and message
27
+ #
28
+ # https://developer.send.io/docs/api
29
+ def send(params = [], options: {})
30
+ path = "emails/batch"
31
+
32
+ Sendio::Request.new(path, params, "post", options: options).perform
33
+ end
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,180 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ # broadcasts api wrapper
5
+ module Broadcasts
6
+ class << self
7
+ # https://developer.send.io/docs/api
8
+ # @note A draft needs no fields. With send: true, from, subject, an html or
9
+ # text body and an audience (segment_id, segment_ids or audience: "all")
10
+ # are required.
11
+ # @note Accepted fields: name, from, subject, reply_to, html, text, preview_text,
12
+ # topic_id, segment_id, segment_ids, exclude_segment_ids, audience ("segments"
13
+ # or "all"), unsubscribe_scope ("all" or "list"), tracking (true/false),
14
+ # template_engine ("simple" or "handlebars"), send and scheduled_at.
15
+ # audience_id is deprecated - use segment_id instead.
16
+ # @note When send: true is passed, the broadcast is sent immediately instead of
17
+ # creating a draft. When using send: true, you can also include scheduled_at
18
+ # to schedule the broadcast. Passing scheduled_at without send: true is an error.
19
+ def create(params = {})
20
+ if params[:audience_id] && !params[:segment_id]
21
+ warn "[DEPRECATION] Using audience_id in broadcasts is deprecated. Use segment_id instead."
22
+ end
23
+ path = "broadcasts"
24
+ Sendio::Request.new(path, params, "post").perform
25
+ end
26
+
27
+ # https://developer.send.io/docs/api
28
+ # @note Takes the create fields except send and scheduled_at; only the keys
29
+ # given are changed. The broadcast_id goes in the path, never in the body
30
+ # (once a broadcast is sending or sent, only name can be changed).
31
+ # audience_id is deprecated - use segment_id instead.
32
+ def update(params = {})
33
+ if params[:audience_id] && !params[:segment_id]
34
+ warn "[DEPRECATION] Using audience_id in broadcasts is deprecated. Use segment_id instead."
35
+ end
36
+ broadcast_id, body = extract_broadcast_id(params)
37
+ path = "broadcasts/#{broadcast_id}"
38
+ Sendio::Request.new(path, body, "patch").perform
39
+ end
40
+
41
+ # https://developer.send.io/docs/api
42
+ # @option params [String] :broadcast_id the broadcast to send (path only)
43
+ # @option params [String] :scheduled_at when to send it (optional)
44
+ def send(params = {})
45
+ broadcast_id, body = extract_broadcast_id(params)
46
+ path = "broadcasts/#{broadcast_id}/send"
47
+ Sendio::Request.new(path, body, "post").perform
48
+ end
49
+
50
+ # https://developer.send.io/docs/api
51
+ # @option params [Integer] :limit the maximum number of results to return (optional)
52
+ # @option params [String] :after the cursor for pagination (optional)
53
+ # @option params [String] :before the cursor for pagination (optional)
54
+ # @option params [String] :status only broadcasts with this status (optional)
55
+ # @option params [String] :segment_id only broadcasts sent to this segment (optional)
56
+ # @option params [String] :search only broadcasts matching this text (optional)
57
+ def list(params = {})
58
+ path = Sendio::PaginationHelper.build_paginated_path("broadcasts", params)
59
+ Sendio::Request.new(path, {}, "get").perform
60
+ end
61
+
62
+ # https://developer.send.io/docs/api
63
+ def clicked_links(broadcast_id = "", params = {})
64
+ path = Sendio::PaginationHelper.build_paginated_path("broadcasts/#{broadcast_id}/clicked-links", params)
65
+ Sendio::Request.new(path, {}, "get").perform
66
+ end
67
+
68
+ def cancel(broadcast_id = "")
69
+ path = "broadcasts/#{broadcast_id}/cancel"
70
+ Sendio::Request.new(path, {}, "post").perform
71
+ end
72
+
73
+ # https://developer.send.io/docs/api
74
+ # @note Creates a new draft with the same content as the source, named after it with " (copy)" appended.
75
+ def duplicate(broadcast_id = "")
76
+ path = "broadcasts/#{broadcast_id}/duplicate"
77
+ Sendio::Request.new(path, {}, "post").perform
78
+ end
79
+
80
+ # https://developer.send.io/docs/api
81
+ def remove(broadcast_id = "")
82
+ path = "broadcasts/#{broadcast_id}"
83
+ Sendio::Request.new(path, {}, "delete").perform
84
+ end
85
+
86
+ # https://developer.send.io/docs/api
87
+ def get(broadcast_id = "")
88
+ path = "broadcasts/#{broadcast_id}"
89
+ Sendio::Request.new(path, {}, "get").perform
90
+ end
91
+
92
+ # https://developer.send.io/docs/api
93
+ # @param broadcast_id [String] the broadcast id
94
+ # @param params [Hash] the parameters
95
+ # @option params [String] :type the recipient event type to filter by (required):
96
+ # sent, delivered, opened, clicked, bounced, complained, unsubscribed, suppressed
97
+ # @option params [String] :email filter recipients by email address (optional)
98
+ # @option params [String] :bounce_type filter bounced recipients by bounce type (optional,
99
+ # only valid when type is bounced): permanent, transient, undetermined
100
+ # @option params [Integer] :limit the maximum number of results to return (optional)
101
+ # @option params [String] :after the cursor for pagination (optional)
102
+ # @option params [String] :before the cursor for pagination (optional)
103
+ def recipients(broadcast_id = "", params = {})
104
+ raise ArgumentError, "type is required" if params[:type].nil?
105
+
106
+ base_path = "broadcasts/#{broadcast_id}/recipients"
107
+ path = Sendio::PaginationHelper.build_paginated_path(base_path, params)
108
+ Sendio::Request.new(path, {}, "get").perform
109
+ end
110
+
111
+ # https://developer.send.io/docs/api
112
+ # @note How many contacts an audience reaches now, before anything is saved.
113
+ # @option params [String] :segment_id a single segment (optional)
114
+ # @option params [Array<String>] :segment_ids several segments (optional)
115
+ # @option params [Array<String>] :exclude_segment_ids segments left out (optional)
116
+ # @option params [String] :audience "segments" or "all" (optional)
117
+ # @option params [String] :topic_id only contacts opted in to this topic (optional)
118
+ # @return { object: "broadcast_estimate", recipients:, skipped: { invalid: } }
119
+ def estimate(params = {})
120
+ Sendio::Request.new("broadcasts/estimate", params, "post").perform
121
+ end
122
+
123
+ # https://developer.send.io/docs/api
124
+ # @note Sends a test of the broadcast, subject prefixed [Test].
125
+ # @param broadcast_id [String] the broadcast id
126
+ # @param to [String, Array<String>] 1 to 5 addresses
127
+ def test(broadcast_id = "", to = [])
128
+ path = "broadcasts/#{broadcast_id}/test"
129
+ Sendio::Request.new(path, { to: Array(to) }, "post").perform
130
+ end
131
+
132
+ # https://developer.send.io/docs/api
133
+ def stats(broadcast_id = "")
134
+ path = "broadcasts/#{broadcast_id}/stats"
135
+ Sendio::Request.new(path, {}, "get").perform
136
+ end
137
+
138
+ # https://developer.send.io/docs/api
139
+ # @note Saved versions of a broadcast, newest first.
140
+ # @option params [Integer] :limit the maximum number of results to return (optional)
141
+ # @option params [String] :after the cursor for pagination (optional)
142
+ # @option params [String] :before the cursor for pagination (optional)
143
+ def list_versions(broadcast_id = "", params = {})
144
+ path = Sendio::PaginationHelper.build_paginated_path("broadcasts/#{broadcast_id}/versions", params)
145
+ Sendio::Request.new(path, {}, "get").perform
146
+ end
147
+
148
+ # https://developer.send.io/docs/api
149
+ # @param version [Integer, String] the version_number or version id
150
+ def get_version(broadcast_id = "", version = "")
151
+ path = "broadcasts/#{broadcast_id}/versions/#{version}"
152
+ Sendio::Request.new(path, {}, "get").perform
153
+ end
154
+
155
+ # https://developer.send.io/docs/api
156
+ # @note Only a version's label (name, comment) can change; its content is immutable.
157
+ # @option params [String] :name the version name (optional)
158
+ # @option params [String] :comment the version comment (optional)
159
+ def update_version(broadcast_id = "", version = "", params = {})
160
+ path = "broadcasts/#{broadcast_id}/versions/#{version}"
161
+ Sendio::Request.new(path, params, "patch").perform
162
+ end
163
+
164
+ # https://developer.send.io/docs/api
165
+ # @note Copies a version back into a draft or scheduled broadcast, saved as a new version.
166
+ def restore_version(broadcast_id = "", version = "")
167
+ path = "broadcasts/#{broadcast_id}/versions/#{version}/restore"
168
+ Sendio::Request.new(path, {}, "post").perform
169
+ end
170
+
171
+ private
172
+
173
+ # Splits the broadcast id (path) from the JSON body.
174
+ def extract_broadcast_id(params)
175
+ body = params.reject { |k, _| k.to_s == "broadcast_id" }
176
+ [params[:broadcast_id] || params["broadcast_id"], body]
177
+ end
178
+ end
179
+ end
180
+ end
@@ -0,0 +1,19 @@
1
+ # frozen_string_literal: true
2
+
3
+ # backwards compatibility
4
+ require "sendio/emails"
5
+
6
+ module Sendio
7
+ # Client class.
8
+ class Client
9
+ include Sendio::Emails
10
+
11
+ attr_reader :api_key
12
+
13
+ def initialize(api_key)
14
+ raise ArgumentError, "API Key is not a string" unless api_key.is_a?(String)
15
+
16
+ @api_key = api_key
17
+ end
18
+ end
19
+ end
@@ -0,0 +1,106 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ # Module for managing contact properties
5
+ #
6
+ # Contact properties allow you to store custom data about your contacts
7
+ module ContactProperties
8
+ class << self
9
+ # Create a custom property for your contacts
10
+ #
11
+ # @param params [Hash] Parameters for creating a contact property
12
+ # @option params [String] :key The property key (max 50 characters, alphanumeric and underscores only) (required)
13
+ # @option params [String] :type The property type ('string' or 'number') (required)
14
+ # @option params [String, Integer] :fallback_value The default value when property is not set (must match type)
15
+ #
16
+ # @return [Hash] Response containing the created contact property
17
+ #
18
+ # @example Create a string property
19
+ # Sendio::ContactProperties.create({
20
+ # key: 'company_name',
21
+ # type: 'string',
22
+ # fallback_value: 'Acme Corp'
23
+ # })
24
+ #
25
+ # @example Create a number property
26
+ # Sendio::ContactProperties.create({
27
+ # key: 'age',
28
+ # type: 'number',
29
+ # fallback_value: 0
30
+ # })
31
+ def create(params)
32
+ path = "contact-properties"
33
+ Sendio::Request.new(path, params, "post").perform
34
+ end
35
+
36
+ # Retrieve a contact property by its ID
37
+ #
38
+ # @param contact_property_id [String] The Contact Property ID
39
+ #
40
+ # @return [Hash] Response containing the contact property details
41
+ #
42
+ # @example Get a contact property
43
+ # Sendio::ContactProperties.get('b6d24b8e-af0b-4c3c-be0c-359bbd97381e')
44
+ def get(contact_property_id = "")
45
+ path = "contact-properties/#{contact_property_id}"
46
+ Sendio::Request.new(path, {}, "get").perform
47
+ end
48
+
49
+ # Retrieve a list of contact properties
50
+ #
51
+ # @param params [Hash] Optional query parameters
52
+ # @option params [Integer] :limit Number of contact properties to retrieve (1-100, default: 20)
53
+ # @option params [String] :after The ID after which to retrieve more contact properties
54
+ # @option params [String] :before The ID before which to retrieve more contact properties
55
+ #
56
+ # @return [Hash] Response containing list of contact properties
57
+ #
58
+ # @example List all contact properties
59
+ # Sendio::ContactProperties.list
60
+ #
61
+ # @example List with pagination
62
+ # Sendio::ContactProperties.list({ limit: 10, after: 'cursor_123' })
63
+ def list(params = {})
64
+ path = Sendio::PaginationHelper.build_paginated_path("contact-properties", params)
65
+ Sendio::Request.new(path, {}, "get").perform
66
+ end
67
+
68
+ # Update an existing contact property
69
+ #
70
+ # Note: The 'key' and 'type' fields cannot be changed after creation
71
+ #
72
+ # @param params [Hash] Parameters for updating a contact property
73
+ # @option params [String] :id The Contact Property ID (required)
74
+ # @option params [String, Integer] :fallback_value The default value when property is not set
75
+ # (must match property type)
76
+ #
77
+ # @return [Hash] Response containing the updated contact property
78
+ #
79
+ # @example Update fallback value
80
+ # Sendio::ContactProperties.update({
81
+ # id: 'b6d24b8e-af0b-4c3c-be0c-359bbd97381e',
82
+ # fallback_value: 'Example Company'
83
+ # })
84
+ def update(params)
85
+ raise ArgumentError, "Missing `id` field" if params[:id].nil?
86
+
87
+ contact_property_id = params[:id]
88
+ path = "contact-properties/#{contact_property_id}"
89
+ Sendio::Request.new(path, params, "patch").perform
90
+ end
91
+
92
+ # Remove an existing contact property
93
+ #
94
+ # @param contact_property_id [String] The Contact Property ID
95
+ #
96
+ # @return [Hash] Response containing the deleted property ID and confirmation
97
+ #
98
+ # @example Delete a contact property
99
+ # Sendio::ContactProperties.remove('b6d24b8e-af0b-4c3c-be0c-359bbd97381e')
100
+ def remove(contact_property_id = "")
101
+ path = "contact-properties/#{contact_property_id}"
102
+ Sendio::Request.new(path, {}, "delete").perform
103
+ end
104
+ end
105
+ end
106
+ end
@@ -0,0 +1,64 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ module Contacts
5
+ # Contact Imports API wrapper
6
+ module Imports
7
+ class << self
8
+ #
9
+ # Create a new contact import from a CSV file.
10
+ #
11
+ # @param params [Hash] the parameters
12
+ # @option params [String, IO] :file CSV file content (required). Maximum size is 50MB.
13
+ # @option params [Hash, String] :column_map optional mapping of contact fields to CSV columns.
14
+ # Accepts a Hash (will be JSON-encoded) or a pre-encoded JSON String.
15
+ # @option params [String] :on_conflict optional conflict strategy: 'upsert' or 'skip' (default 'skip').
16
+ # @option params [Array, String] :segments optional list of segment IDs to add contacts to.
17
+ # Accepts an Array of segment ID strings (will be JSON-encoded as [{"id":"..."}])
18
+ # or a pre-encoded JSON String.
19
+ # @option params [Array, String] :topics optional list of topic subscription objects.
20
+ # Each element must be a Hash with `id` (String) and `subscription` ('opt_in' or 'opt_out').
21
+ # Accepts an Array of Hashes (will be JSON-encoded) or a pre-encoded JSON String.
22
+ #
23
+ # https://developer.send.io/docs/api
24
+ def create(params)
25
+ raise ArgumentError, "Missing required `file` field" if params[:file].nil?
26
+
27
+ # Normalize segments: convert array of IDs to [{id: ...}] format
28
+ if params[:segments].is_a?(Array)
29
+ params = params.merge(segments: params[:segments].map { |s| s.is_a?(String) ? { id: s } : s })
30
+ end
31
+
32
+ Sendio::MultipartRequest.new("contacts/imports", params, "post").perform
33
+ end
34
+
35
+ #
36
+ # Retrieve a single contact import by ID.
37
+ #
38
+ # @param id [String] the contact import ID (required)
39
+ #
40
+ # https://developer.send.io/docs/api
41
+ def get(id)
42
+ raise ArgumentError, "Missing required `id` field" if id.nil? || id.empty?
43
+
44
+ Sendio::Request.new("contacts/imports/#{id}", {}, "get").perform
45
+ end
46
+
47
+ #
48
+ # Retrieve a list of contact imports.
49
+ #
50
+ # @param params [Hash] optional filtering and pagination parameters
51
+ # @option params [String] :status filter by status: 'queued', 'in_progress', 'completed', or 'failed'
52
+ # @option params [Integer] :limit number of results to return
53
+ # @option params [String] :after cursor for forward pagination
54
+ # @option params [String] :before cursor for backward pagination
55
+ #
56
+ # https://developer.send.io/docs/api
57
+ def list(params = {})
58
+ path = Sendio::PaginationHelper.build_paginated_path("contacts/imports", params)
59
+ Sendio::Request.new(path, {}, "get").perform
60
+ end
61
+ end
62
+ end
63
+ end
64
+ end
@@ -0,0 +1,66 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ module Contacts
5
+ # Contact Segments api wrapper
6
+ module Segments
7
+ class << self
8
+ #
9
+ # List all segments for a contact
10
+ #
11
+ # @param params [Hash] the parameters
12
+ # @option params [String] :contact_id the contact id (either contact_id or email is required)
13
+ # @option params [String] :email the contact email (either contact_id or email is required)
14
+ # @option params [Integer] :limit the maximum number of results to return (optional)
15
+ # @option params [String] :after the cursor for pagination (optional)
16
+ # @option params [String] :before the cursor for pagination (optional)
17
+ #
18
+ # https://developer.send.io/docs/api
19
+ def list(params)
20
+ raise ArgumentError, "contact_id or email is required" if params[:contact_id].nil? && params[:email].nil?
21
+
22
+ identifier = params[:contact_id] || params[:email]
23
+ base_path = "contacts/#{identifier}/segments"
24
+ path = Sendio::PaginationHelper.build_paginated_path(base_path, params)
25
+ Sendio::Request.new(path, {}, "get").perform
26
+ end
27
+
28
+ #
29
+ # Add a contact to a segment
30
+ #
31
+ # @param params [Hash] the parameters
32
+ # @option params [String] :contact_id the contact id (either contact_id or email is required)
33
+ # @option params [String] :email the contact email (either contact_id or email is required)
34
+ # @option params [String] :segment_id the segment id (required)
35
+ #
36
+ # https://developer.send.io/docs/api
37
+ def add(params)
38
+ raise ArgumentError, "contact_id or email is required" if params[:contact_id].nil? && params[:email].nil?
39
+ raise ArgumentError, "segment_id is required" if params[:segment_id].nil?
40
+
41
+ identifier = params[:contact_id] || params[:email]
42
+ path = "contacts/#{identifier}/segments/#{params[:segment_id]}"
43
+ Sendio::Request.new(path, {}, "post").perform
44
+ end
45
+
46
+ #
47
+ # Remove a contact from a segment
48
+ #
49
+ # @param params [Hash] the parameters
50
+ # @option params [String] :contact_id the contact id (either contact_id or email is required)
51
+ # @option params [String] :email the contact email (either contact_id or email is required)
52
+ # @option params [String] :segment_id the segment id (required)
53
+ #
54
+ # https://developer.send.io/docs/api
55
+ def remove(params)
56
+ raise ArgumentError, "contact_id or email is required" if params[:contact_id].nil? && params[:email].nil?
57
+ raise ArgumentError, "segment_id is required" if params[:segment_id].nil?
58
+
59
+ identifier = params[:contact_id] || params[:email]
60
+ path = "contacts/#{identifier}/segments/#{params[:segment_id]}"
61
+ Sendio::Request.new(path, {}, "delete").perform
62
+ end
63
+ end
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,80 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sendio
4
+ module Contacts
5
+ # Module for managing contact topic subscriptions
6
+ #
7
+ # Allows you to manage which topics contacts are subscribed to
8
+ module Topics
9
+ class << self
10
+ # Retrieve a list of topics subscriptions for a contact
11
+ #
12
+ # @param params [Hash] Parameters for listing topics
13
+ # @option params [String] :id The Contact ID (either :id or :email must be provided)
14
+ # @option params [String] :email The Contact Email (either :id or :email must be provided)
15
+ # @option params [Integer] :limit Number of topics to retrieve (1-100)
16
+ # @option params [String] :after The ID after which to retrieve more topics
17
+ # @option params [String] :before The ID before which to retrieve more topics
18
+ #
19
+ # @return [Hash] Response containing list of topics with subscription status
20
+ #
21
+ # @example List topics by contact ID
22
+ # Sendio::Contacts::Topics.list(id: 'e169aa45-1ecf-4183-9955-b1499d5701d3')
23
+ #
24
+ # @example List topics by contact email
25
+ # Sendio::Contacts::Topics.list(email: 'steve.wozniak@gmail.com')
26
+ #
27
+ # @example List topics with pagination
28
+ # Sendio::Contacts::Topics.list(id: 'contact-id', limit: 10, after: 'cursor_123')
29
+ def list(params = {})
30
+ contact_identifier = params[:id] || params[:email]
31
+ raise ArgumentError, "Either :id or :email must be provided" if contact_identifier.nil?
32
+
33
+ pagination_params = params.slice(:limit, :after, :before)
34
+ base_path = "contacts/#{contact_identifier}/topics"
35
+ path = Sendio::PaginationHelper.build_paginated_path(base_path, pagination_params)
36
+
37
+ Sendio::Request.new(path, {}, "get").perform
38
+ end
39
+
40
+ # Update topic subscriptions for a contact
41
+ #
42
+ # @param params [Hash] Parameters for updating topics
43
+ # @option params [String] :id The Contact ID (either :id or :email must be provided)
44
+ # @option params [String] :email The Contact Email (either :id or :email must be provided)
45
+ # @option params [Array<Hash>] :topics Array of topic subscription updates
46
+ # Each topic hash should contain:
47
+ # - :id [String] The Topic ID (required)
48
+ # - :subscription [String] The subscription action: 'opt_in' or 'opt_out' (required)
49
+ #
50
+ # @return [Hash] Response containing the contact ID
51
+ #
52
+ # @example Update by contact ID
53
+ # Sendio::Contacts::Topics.update({
54
+ # id: 'e169aa45-1ecf-4183-9955-b1499d5701d3',
55
+ # topics: [
56
+ # { id: 'b6d24b8e-af0b-4c3c-be0c-359bbd97381e', subscription: 'opt_out' },
57
+ # { id: '07d84122-7224-4881-9c31-1c048e204602', subscription: 'opt_in' }
58
+ # ]
59
+ # })
60
+ #
61
+ # @example Update by contact email
62
+ # Sendio::Contacts::Topics.update({
63
+ # email: 'steve.wozniak@gmail.com',
64
+ # topics: [
65
+ # { id: '07d84122-7224-4881-9c31-1c048e204602', subscription: 'opt_out' }
66
+ # ]
67
+ # })
68
+ def update(params)
69
+ contact_identifier = params[:id] || params[:email]
70
+ raise ArgumentError, "Either :id or :email must be provided" if contact_identifier.nil?
71
+
72
+ path = "contacts/#{contact_identifier}/topics"
73
+ body = params[:topics]
74
+
75
+ Sendio::Request.new(path, body, "patch").perform
76
+ end
77
+ end
78
+ end
79
+ end
80
+ end