Class: GandiV5::Email::Forward

Inherits:
Object
  • Object
show all
Includes:
Data
Defined in:
lib/gandi_v5/email/forward.rb

Overview

A forwarding address that lives within a domain.

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Data

#from_gandi, included, #initialize, #to_gandi, #to_h, #values_at

Instance Attribute Details

#destinations ⇒ Array<String> (readonly)

Returns list of destination email addresses.

Returns:

  • (Array<String>) —

    list of destination email addresses.



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
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
101
102
103
104
105
106
 
# File 'lib/gandi_v5/email/forward.rb', line 13

class Forward
  include GandiV5::Data

  members :source, :fqdn
  member :destinations, array: true

  # Delete the forwarding.
  # @see https://api.gandi.net/docs/email/#delete-v5-email-forwards-domain-source
  # @return [String] The confirmation message from Gandi.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def delete
    _response, data = GandiV5.delete url
    data['message']
  end

  # Update the forwarding.
  # @see https://api.gandi.net/docs/email/#put-v5-email-forwards-domain-source
  # @param destinations [Array<String, #to_s>] new list of destination email addresses.
  # @return [String] The confirmation message from Gandi.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def update(*destinations)
    fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

    _response, data = GandiV5.put url, { destinations: destinations }.to_json
    @destinations = destinations.map(&:to_s)
    data['message']
  end

  # Returns the string representation of the forwarding.
  # @return [String]
  def to_s
    "#{source}@#{fqdn} -> #{destinations.join(', ')}"
  end

  # Create a new forward.
  # @see https://api.gandi.net/docs/email/#post-v5-email-forwards-domain
  # @param fqdn [String, #to_s] the fully qualified domain name for the forward.
  # @param source [String, #to_s]
  #   the source email address ("alice" rather than "[email protected]").
  # @param destinations [Array<String, #to_s>] list of destination email addresses.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def self.create(fqdn, source, *destinations)
    fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

    body = {
      source: source,
      destinations: destinations
    }.to_json
    _response, _data = GandiV5.post url(fqdn), body

    new fqdn: fqdn, source: source, destinations: destinations
  end

  # List forwards for a domain.
  # @see https://api.gandi.net/docs/email/#get-v5-email-forwards-domain
  # @param fqdn [String, #to_s] the fully qualified domain name for the forwards.
  # @param page [Integer, #each<Integer>] which page(s) of results to get.
  #   If page is not provided keep querying until an empty list is returned.
  #   If page responds to .each then iterate until an empty list is returned.
  # @param per_page [Integer, #to_s] (optional default 100) how many results ot get per page.
  # @param sort_by [#to_s] (optional default "login")
  #   how to sort the results ("login", "-login").
  # @param source [String] (optional) filter the source (pattern)
  #   e.g. ("alice" "*lice", "alic*").
  # @return [Array<GandiV5::Email::Forward>]
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def self.list(fqdn, page: (1..), **params)
    page = [page.to_i] unless page.respond_to?(:each)

    params.reject! { |_k, v| v.nil? }

    mailboxes = []
    page.each do |page_number|
      _response, data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
      break if data.empty?

      mailboxes += data.map { |mailbox| from_gandi mailbox.merge(fqdn: fqdn) }
      break if data.count < params.fetch(:per_page, 100)
    end
    mailboxes
  end

  private

  def url
    "#{BASE}email/forwards/#{CGI.escape fqdn}/#{CGI.escape source}"
  end

  def self.url(fqdn, source = nil)
    "#{BASE}email/forwards/#{CGI.escape fqdn}" +
      (source ? "/#{CGI.escape source}" : '')
  end
  private_class_method :url
end

#fqdn ⇒ String (readonly)

Returns domain name.

Returns:

  • (String) —

    domain name.



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
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
101
102
103
104
105
106
 
# File 'lib/gandi_v5/email/forward.rb', line 13

class Forward
  include GandiV5::Data

  members :source, :fqdn
  member :destinations, array: true

  # Delete the forwarding.
  # @see https://api.gandi.net/docs/email/#delete-v5-email-forwards-domain-source
  # @return [String] The confirmation message from Gandi.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def delete
    _response, data = GandiV5.delete url
    data['message']
  end

  # Update the forwarding.
  # @see https://api.gandi.net/docs/email/#put-v5-email-forwards-domain-source
  # @param destinations [Array<String, #to_s>] new list of destination email addresses.
  # @return [String] The confirmation message from Gandi.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def update(*destinations)
    fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

    _response, data = GandiV5.put url, { destinations: destinations }.to_json
    @destinations = destinations.map(&:to_s)
    data['message']
  end

  # Returns the string representation of the forwarding.
  # @return [String]
  def to_s
    "#{source}@#{fqdn} -> #{destinations.join(', ')}"
  end

  # Create a new forward.
  # @see https://api.gandi.net/docs/email/#post-v5-email-forwards-domain
  # @param fqdn [String, #to_s] the fully qualified domain name for the forward.
  # @param source [String, #to_s]
  #   the source email address ("alice" rather than "[email protected]").
  # @param destinations [Array<String, #to_s>] list of destination email addresses.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def self.create(fqdn, source, *destinations)
    fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

    body = {
      source: source,
      destinations: destinations
    }.to_json
    _response, _data = GandiV5.post url(fqdn), body

    new fqdn: fqdn, source: source, destinations: destinations
  end

  # List forwards for a domain.
  # @see https://api.gandi.net/docs/email/#get-v5-email-forwards-domain
  # @param fqdn [String, #to_s] the fully qualified domain name for the forwards.
  # @param page [Integer, #each<Integer>] which page(s) of results to get.
  #   If page is not provided keep querying until an empty list is returned.
  #   If page responds to .each then iterate until an empty list is returned.
  # @param per_page [Integer, #to_s] (optional default 100) how many results ot get per page.
  # @param sort_by [#to_s] (optional default "login")
  #   how to sort the results ("login", "-login").
  # @param source [String] (optional) filter the source (pattern)
  #   e.g. ("alice" "*lice", "alic*").
  # @return [Array<GandiV5::Email::Forward>]
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def self.list(fqdn, page: (1..), **params)
    page = [page.to_i] unless page.respond_to?(:each)

    params.reject! { |_k, v| v.nil? }

    mailboxes = []
    page.each do |page_number|
      _response, data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
      break if data.empty?

      mailboxes += data.map { |mailbox| from_gandi mailbox.merge(fqdn: fqdn) }
      break if data.count < params.fetch(:per_page, 100)
    end
    mailboxes
  end

  private

  def url
    "#{BASE}email/forwards/#{CGI.escape fqdn}/#{CGI.escape source}"
  end

  def self.url(fqdn, source = nil)
    "#{BASE}email/forwards/#{CGI.escape fqdn}" +
      (source ? "/#{CGI.escape source}" : '')
  end
  private_class_method :url
end

#source ⇒ String (readonly)

Returns the source email address (“alice” rather than “[email protected]”).

Returns:

  • (String) —

    the source email address (“alice” rather than “[email protected]”).



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
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
101
102
103
104
105
106
 
# File 'lib/gandi_v5/email/forward.rb', line 13

class Forward
  include GandiV5::Data

  members :source, :fqdn
  member :destinations, array: true

  # Delete the forwarding.
  # @see https://api.gandi.net/docs/email/#delete-v5-email-forwards-domain-source
  # @return [String] The confirmation message from Gandi.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def delete
    _response, data = GandiV5.delete url
    data['message']
  end

  # Update the forwarding.
  # @see https://api.gandi.net/docs/email/#put-v5-email-forwards-domain-source
  # @param destinations [Array<String, #to_s>] new list of destination email addresses.
  # @return [String] The confirmation message from Gandi.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def update(*destinations)
    fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

    _response, data = GandiV5.put url, { destinations: destinations }.to_json
    @destinations = destinations.map(&:to_s)
    data['message']
  end

  # Returns the string representation of the forwarding.
  # @return [String]
  def to_s
    "#{source}@#{fqdn} -> #{destinations.join(', ')}"
  end

  # Create a new forward.
  # @see https://api.gandi.net/docs/email/#post-v5-email-forwards-domain
  # @param fqdn [String, #to_s] the fully qualified domain name for the forward.
  # @param source [String, #to_s]
  #   the source email address ("alice" rather than "[email protected]").
  # @param destinations [Array<String, #to_s>] list of destination email addresses.
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def self.create(fqdn, source, *destinations)
    fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

    body = {
      source: source,
      destinations: destinations
    }.to_json
    _response, _data = GandiV5.post url(fqdn), body

    new fqdn: fqdn, source: source, destinations: destinations
  end

  # List forwards for a domain.
  # @see https://api.gandi.net/docs/email/#get-v5-email-forwards-domain
  # @param fqdn [String, #to_s] the fully qualified domain name for the forwards.
  # @param page [Integer, #each<Integer>] which page(s) of results to get.
  #   If page is not provided keep querying until an empty list is returned.
  #   If page responds to .each then iterate until an empty list is returned.
  # @param per_page [Integer, #to_s] (optional default 100) how many results ot get per page.
  # @param sort_by [#to_s] (optional default "login")
  #   how to sort the results ("login", "-login").
  # @param source [String] (optional) filter the source (pattern)
  #   e.g. ("alice" "*lice", "alic*").
  # @return [Array<GandiV5::Email::Forward>]
  # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
  def self.list(fqdn, page: (1..), **params)
    page = [page.to_i] unless page.respond_to?(:each)

    params.reject! { |_k, v| v.nil? }

    mailboxes = []
    page.each do |page_number|
      _response, data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
      break if data.empty?

      mailboxes += data.map { |mailbox| from_gandi mailbox.merge(fqdn: fqdn) }
      break if data.count < params.fetch(:per_page, 100)
    end
    mailboxes
  end

  private

  def url
    "#{BASE}email/forwards/#{CGI.escape fqdn}/#{CGI.escape source}"
  end

  def self.url(fqdn, source = nil)
    "#{BASE}email/forwards/#{CGI.escape fqdn}" +
      (source ? "/#{CGI.escape source}" : '')
  end
  private_class_method :url
end

Class Method Details

.create(fqdn, source, *destinations) ⇒ Object

Create a new forward.

Parameters:

  • fqdn (String, #to_s) —

    the fully qualified domain name for the forward.

  • source (String, #to_s) —

    the source email address (“alice” rather than “[email protected]”).

  • destinations (Array<String, #to_s>) —

    list of destination email addresses.

Raises:

See Also:



54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/gandi_v5/email/forward.rb', line 54

def self.create(fqdn, source, *destinations)
  fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

  body = {
    source: source,
    destinations: destinations
  }.to_json
  _response, _data = GandiV5.post url(fqdn), body

  new fqdn: fqdn, source: source, destinations: destinations
end

.list(fqdn, page: (1..), **params) ⇒ Array<GandiV5::Email::Forward>

List forwards for a domain.

Parameters:

  • fqdn (String, #to_s) —

    the fully qualified domain name for the forwards.

  • page (Integer, #each<Integer>) (defaults to: (1..)) —

    which page(s) of results to get. If page is not provided keep querying until an empty list is returned. If page responds to .each then iterate until an empty list is returned.

  • per_page (Integer, #to_s) —

    (optional default 100) how many results ot get per page.

  • sort_by (#to_s) —

    (optional default “login”) how to sort the results (“login”, “-login”).

  • source (String) —

    (optional) filter the source (pattern) e.g. (“alice” “*lice”, “alic*”).

Returns:

Raises:

See Also:



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/gandi_v5/email/forward.rb', line 79

def self.list(fqdn, page: (1..), **params)
  page = [page.to_i] unless page.respond_to?(:each)

  params.reject! { |_k, v| v.nil? }

  mailboxes = []
  page.each do |page_number|
    _response, data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
    break if data.empty?

    mailboxes += data.map { |mailbox| from_gandi mailbox.merge(fqdn: fqdn) }
    break if data.count < params.fetch(:per_page, 100)
  end
  mailboxes
end

Instance Method Details

#delete ⇒ String

Delete the forwarding.

Returns:

  • (String) —

    The confirmation message from Gandi.

Raises:

See Also:



23
24
25
26
 
# File 'lib/gandi_v5/email/forward.rb', line 23

def delete
  _response, data = GandiV5.delete url
  data['message']
end

#to_s ⇒ String

Returns the string representation of the forwarding.

Returns:

  • (String) 


43
44
45
 
# File 'lib/gandi_v5/email/forward.rb', line 43

def to_s
  "#{source}@#{fqdn} -> #{destinations.join(', ')}"
end

#update(*destinations) ⇒ String

Update the forwarding.

Parameters:

  • destinations (Array<String, #to_s>) —

    new list of destination email addresses.

Returns:

  • (String) —

    The confirmation message from Gandi.

Raises:

See Also:



33
34
35
36
37
38
39
 
# File 'lib/gandi_v5/email/forward.rb', line 33

def update(*destinations)
  fail ArgumentError, 'destinations can\'t be empty' if destinations.none?

  _response, data = GandiV5.put url, { destinations: destinations }.to_json
  @destinations = destinations.map(&:to_s)
  data['message']
end