Class: Mail::Sympa

Inherits:
Object
  • Object
show all
Defined in:
lib/mail/sympa.rb

Overview

The Sympa module encapsulates the various Sympa server SOAP methods

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION =

The version of the mail-sympa library.

'0.1.0'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(endpoint, namespace = 'urn:sympasoap') ⇒ Sympa

Creates and returns a new Mail::Sympa object based on the endpoint (the endpoint URL) and a namespace which defaults to ‘urn:sympasoap’.

Example:

sympa = Mail::Sympa.new('http://your.sympa.home/sympasoap')



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
 
# File 'lib/mail/sympa.rb', line 29

def initialize(endpoint, namespace = 'urn:sympasoap')
  @endpoint  = endpoint.to_s # Allow for URI objects
  @namespace = namespace

  @soap = SOAP::RPC::Driver.new(endpoint, namespace)

  @email    = nil
  @password = nil
  @cookie   = nil

  @soap.add_method('login', 'email', 'password')
  
  @soap.add_method(
    'authenticateAndRun',
    'email',
    'cookie',
    'service',
    'parameters'
  )

  @soap.add_method(
    'authenticateRemoteAppAndRun',
    'appname',
    'apppassword',
    'vars',
    'service',
    'parameters'
  )
end

Instance Attribute Details

The session cookie returned by the login method.



14
15
16
 
# File 'lib/mail/sympa.rb', line 14

def cookie
  @cookie
end

#endpoint ⇒ Object (readonly) Also known as: url

The endpoint URL of the SOAP service.



17
18
19
 
# File 'lib/mail/sympa.rb', line 17

def endpoint
  @endpoint
end

#namespace ⇒ Object (readonly)

The URN namespace. The default is ‘urn:sympasoap’.



20
21
22
 
# File 'lib/mail/sympa.rb', line 20

def namespace
  @namespace
end

Instance Method Details

#add(email, list_name, name, quiet = true) ⇒ Object

Adds the given email to list_name using name (gecos). If quiet is set to true (the default) then no email notification is sent. – TODO: Determine why this method does not return a boolean.

Raises:



199
200
201
202
 
# File 'lib/mail/sympa.rb', line 199

def add(email, list_name, name, quiet=true)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'add', [list_name, email, name, quiet])
end

#am_i?(user, list_name, function = 'editor') ⇒ Boolean Also known as: amI

Returns a boolean indicating whether or not user has function on list_name. The two possible values for function are ‘editor’ and ‘owner’.

Returns:

  • (Boolean)

Raises:



182
183
184
185
186
187
188
189
190
 
# File 'lib/mail/sympa.rb', line 182

def am_i?(user, list_name, function = 'editor')
  raise Error, 'must login first' unless @cookie

  unless ['editor', 'owner'].include?(function)
    raise Error, 'invalid function name "#{editor}"'
  end

  @soap.authenticateAndRun(@email, @cookie, 'amI', [list_name, function, user])
end

#complex_lists(topic = '', sub_topic = '') ⇒ Object Also known as: complexLists

Returns an array of available mailing lists in complex object format, i.e. these are SOAP::Mapping objects that you can call methods on.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

sympa.complex_lists.each{ |list|
  puts list.subject
  puts list.homepage
}



105
106
107
108
109
 
# File 'lib/mail/sympa.rb', line 105

def complex_lists(topic='', sub_topic='')
  raise Error 'must login first' unless @cookie
  args = [topic, sub_topic]
  @soap.authenticateAndRun(@email, @cookie, 'complexLists', args)
end

#complex_which(user, app_name, app_passwd) ⇒ Object Also known as: complexWhich

Same as the Sympa#which method, but returns an array of SOAP::Mapping objects that you can call methods on.

Raises:



171
172
173
174
 
# File 'lib/mail/sympa.rb', line 171

def complex_which(user, app_name, app_passwd)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateRemoteAppAndRun(app_name, app_passwd, user, 'complexWhich', [''])
end

#del(email, list_name, quiet = true) ⇒ Object Also known as: delete

Deletes the given email from list_name. If quiet is set to true (the default) then no email notification is sent. – TODO: Determine why this method does not return a boolean.

Raises:



209
210
211
212
 
# File 'lib/mail/sympa.rb', line 209

def del(email, list_name, quiet=true)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'del', [list_name, email, quiet])
end

#info(list_name) ⇒ Object

Returns a description about the given list_name. This is a SOAP::Mapping object.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

info = sympa.info(list)

puts info.subject
puts info.homepage
puts info.isOwner

Raises:



127
128
129
130
 
# File 'lib/mail/sympa.rb', line 127

def info(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'info', [list_name])
end

#lists(topic = '', sub_topic = '') ⇒ Object

Returns an array of available mailing lists based on topic and sub_topic. If sub_topic is nil then all sub-topics are returned. If topic is nil then all lists are returned.

The returned lists contains an array of strings. If you prefer objects with methods corresponding to keys, see complex_lists instead.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

sympa.lists.each{ |list| puts list }



87
88
89
90
 
# File 'lib/mail/sympa.rb', line 87

def lists(topic='', sub_topic='')
  raise Error 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'lists', [topic, sub_topic])
end

#login(email, password) ⇒ Object

Authenticate with the Sympa server. This method must be called before any other methods can be used successfully.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)



67
68
69
70
71
 
# File 'lib/mail/sympa.rb', line 67

def (email, password) 
  @email    = email
  @password = password
  @cookie   = @soap.(email, password)
end

#review(list_name) ⇒ Object

Returns an array of members that belong to the given list_name.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

sympa.review(list)

Raises:



141
142
143
144
 
# File 'lib/mail/sympa.rb', line 141

def review(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'review', [list_name])
end

#signoff(list_name) ⇒ Object Also known as: unsubscribe

Removes the currently logged in user from list_name.

Raises:



224
225
226
227
 
# File 'lib/mail/sympa.rb', line 224

def signoff(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'signoff', [list_name, @email])
end

#subscribe(list_name, name = @email) ⇒ Object

Subscribes the currently logged in user to list_name. By default the name (gecos) will be the email address.

Raises:



217
218
219
220
 
# File 'lib/mail/sympa.rb', line 217

def subscribe(list_name, name = @email)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'subscribe', [list_name, name])
end

#which(user, app_name, app_passwd) ⇒ Object

Returns an array of lists that the user is subscribed to. The user should include the proxy variable setup in the trusted_applications.conf file.

The app_name is whatever is set in your trusted_applications.conf file. The app_password for that app must also be provided.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

# If vars contains USER_EMAIL
sympa.which('[email protected]', 'my_app', 'my_password')

An alternative is to use complex_lists + review, though it’s slower.

Raises:



163
164
165
166
 
# File 'lib/mail/sympa.rb', line 163

def which(user, app_name, app_passwd)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateRemoteAppAndRun(app_name, app_passwd, user, 'which', [''])
end