Class: Mailgun::Suppressions

Inherits:
Object
  • Object
show all
Defined in:
lib/mailgun/suppressions.rb

Overview

The Mailgun::Suppressions object makes it easy to manage “suppressions” attached to an account. “Suppressions” means bounces, unsubscribes, and complaints.

Instance Method Summary collapse

Constructor Details

#initialize(client, domain) ⇒ Suppressions


13
14
15
16
17
18
19
# File 'lib/mailgun/suppressions.rb', line 13

def initialize(client, domain)
  @client = client
  @domain = domain

  @paging_next = nil
  @paging_prev = nil
end

Instance Method Details

#create_bounce(params = {}) ⇒ Object


51
52
53
# File 'lib/mailgun/suppressions.rb', line 51

def create_bounce(params = {})
  @client.post("#{@domain/bounces}", params)
end

#create_bounces(data) ⇒ Response, Array

Creates multiple bounces on the Mailgun API. If a bounce does not have a valid structure, it will be added to a list of unsendable bounces. The list of unsendable bounces will be returned at the end of this operation.

If more than 999 bounce entries are provided, the list will be split and recursive calls will be made.


64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
# File 'lib/mailgun/suppressions.rb', line 64

def create_bounces(data)
  # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
  split_return = []
  if data.length >= 1000 then
    resp, resp_l = create_bounces data[999..-1]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.length == 0 then
    return nil, []
  end

  valid = []
  # Validate the bounces given
  # NOTE: `data` could potentially be very large (1000 elements) so it is
  # more efficient to pop from data and push into a different array as
  # opposed to possibly copying the entire array to another array.
  while not data.empty? do
    bounce = data.pop
    # Bounces MUST contain a `address` key.
    if not bounce.include? :address then
      raise Mailgun::ParameterError.new "Bounce MUST include a :address key: #{bounce}"
    end

    bounce.each do |k, v|
      # Hash values MUST be strings.
      if not v.is_a? String then
        bounce[k] = v.to_s
      end
    end

    valid.push bounce
  end

  response = @client.post("#{@domain}/bounces", valid.to_json, { "Content-Type" => "application/json" })
  return response, split_return
end

#create_complaint(params = {}) ⇒ Object


190
191
192
# File 'lib/mailgun/suppressions.rb', line 190

def create_complaint(params = {})
  @client.post("#{@domain}/complaints", params)
end

#create_complaints(data) ⇒ Response, Array

Creates multiple complaints on the Mailgun API. If a complaint does not have a valid structure, it will be added to a list of unsendable complaints. The list of unsendable complaints will be returned at the end of this operation.

If more than 999 complaint entries are provided, the list will be split and recursive calls will be made.


203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
# File 'lib/mailgun/suppressions.rb', line 203

def create_complaints(data)
  # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
  split_return = []
  if data.length >= 1000 then
    resp, resp_l = create_complaints data[999..-1]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.length == 0 then
    return nil, []
  end

  valid = []
  # Validate the complaints given
  while not data.empty? do
    complaint = data.pop
    # complaints MUST contain a `address` key.
    if not complaint.include? :address then
      raise Mailgun::ParameterError.new "Complaint MUST include a :address key: #{complaint}"
    end

    complaint.each do |k, v|
      # Hash values MUST be strings.
      if not v.is_a? String then
        complaint[k] = v.to_s
      end
    end

    valid.push complaint
  end

  response = @client.post("#{@domain}/complaints", valid.to_json, { "Content-Type" => "application/json" })
  return response, split_return
end

#create_unsubscribe(params = {}) ⇒ Object


124
125
126
# File 'lib/mailgun/suppressions.rb', line 124

def create_unsubscribe(params = {})
  @client.post("#{@domain}/unsubscribes", params)
end

#create_unsubscribes(data) ⇒ Response, Array

Creates multiple unsubscribes on the Mailgun API. If an unsubscribe does not have a valid structure, it will be added to a list of unsendable unsubscribes. The list of unsendable unsubscribes will be returned at the end of this operation.

If more than 999 unsubscribe entries are provided, the list will be split and recursive calls will be made.


137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# File 'lib/mailgun/suppressions.rb', line 137

def create_unsubscribes(data)
  # `data` should be a list of hashes, with each hash containing *at least* an `address` key.
  split_return = []
  if data.length >= 1000 then
    resp, resp_l = create_unsubscribes data[999..-1]
    split_return.push(resp)
    split_return.concat(resp_l)
    data = data[0..998]
  elsif data.length == 0 then
    return nil, []
  end

  valid = []
  # Validate the unsubscribes given
  while not data.empty? do
    unsubscribe = data.pop
    # unsubscribes MUST contain a `address` key.
    if not unsubscribe.include? :address then
      raise Mailgun::ParameterError.new "Unsubscribe MUST include a :address key: #{unsubscribe}"
    end

    unsubscribe.each do |k, v|
      # Hash values MUST be strings.
      if not v.is_a? String then
        unsubscribe[k] = v.to_s
      end
    end

    valid.push unsubscribe
  end

  response = @client.post("#{@domain}/unsubscribes", valid.to_json, { "Content-Type" => "application/json" })
  return response, split_return
end

#delete_all_bouncesObject


106
107
108
# File 'lib/mailgun/suppressions.rb', line 106

def delete_all_bounces
  @client.delete("#{@domain}/bounces")
end

#delete_bounce(address) ⇒ Object


102
103
104
# File 'lib/mailgun/suppressions.rb', line 102

def delete_bounce(address)
  @client.delete("#{@domain}/bounces/#{address}")
end

#delete_complaint(address) ⇒ Object


238
239
240
# File 'lib/mailgun/suppressions.rb', line 238

def delete_complaint(address)
  @client.delete("#{@domain}/complaints/#{address}")
end

#delete_unsubscribe(address, params = {}) ⇒ Object


172
173
174
# File 'lib/mailgun/suppressions.rb', line 172

def delete_unsubscribe(address, params = {})
  @client.delete("#{@domain}/unsubscribes/#{address}")
end

#get_bounce(address) ⇒ Object


47
48
49
# File 'lib/mailgun/suppressions.rb', line 47

def get_bounce(address)
  @client.get("#{@domain}/bounces/#{address}", nil)
end

#get_complaint(address) ⇒ Object


186
187
188
# File 'lib/mailgun/suppressions.rb', line 186

def get_complaint(address)
  @client.get("#{@domain}/complaints/#{address}", nil)
end

#get_unsubscribe(address) ⇒ Object


120
121
122
# File 'lib/mailgun/suppressions.rb', line 120

def get_unsubscribe(address)
  @client.get("#{@domain}/unsubscribes/#{address}")
end

#list_bounces(params = {}) ⇒ Object

Bounces Endpoint (/v3/:domain/bounces)


41
42
43
44
45
# File 'lib/mailgun/suppressions.rb', line 41

def list_bounces(params = {})
  response = @client.get("#{@domain}/bounces", params)
  extract_paging response
  response
end

#list_complaints(params = {}) ⇒ Object

Complaints Endpoint (/v3/:domain/complaints)


180
181
182
183
184
# File 'lib/mailgun/suppressions.rb', line 180

def list_complaints(params = {})
  response = @client.get("#{@domain}/complaints", params)
  extract_paging response
  response
end

#list_unsubscribes(params = {}) ⇒ Object

Unsubscribes Endpoint (/v3/:domain/unsubscribes)


114
115
116
117
118
# File 'lib/mailgun/suppressions.rb', line 114

def list_unsubscribes(params = {})
  response = @client.get("#{@domain}/unsubscribes", params)
  extract_paging response
  response
end

#nextObject

Paging operations


25
26
27
28
29
# File 'lib/mailgun/suppressions.rb', line 25

def next
  response = get_from_paging @paging_next[:path], @paging_next[:params]
  extract_paging response
  response
end

#prevObject


31
32
33
34
35
# File 'lib/mailgun/suppressions.rb', line 31

def prev
  response = get_from_paging @paging_prev[:path], @paging_prev[:params]
  extract_paging response
  response
end