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.

'1.2.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')



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

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.



32
33
34
 
# File 'lib/mail/sympa.rb', line 32

def cookie
  @cookie
end

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

The endpoint URL of the SOAP service.



35
36
37
 
# File 'lib/mail/sympa.rb', line 35

def endpoint
  @endpoint
end

#namespace ⇒ Object (readonly)

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



38
39
40
 
# File 'lib/mail/sympa.rb', line 38

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:



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

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:



200
201
202
203
204
205
206
207
208
 
# File 'lib/mail/sympa.rb', line 200

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

#authenticate_remote_app_and_run(app_name, app_password, variables, service, parameters) ⇒ Object Also known as: authenticateRemoteAppAndRun

Run command in trusted context.



270
271
272
 
# File 'lib/mail/sympa.rb', line 270

def authenticate_remote_app_and_run(app_name, app_password, variables, service, parameters)
  @soap.authenticateRemoteAppAndRun( app_name, app_password, variables, service, parameters )
end

#close_list(list_name) ⇒ Object Also known as: closeList

Closes list list_name. Returns boolean.

Raises:



262
263
264
265
 
# File 'lib/mail/sympa.rb', line 262

def close_list(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'closeList', [list_name])
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
}

Raises:



123
124
125
126
127
 
# File 'lib/mail/sympa.rb', line 123

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:



189
190
191
192
 
# File 'lib/mail/sympa.rb', line 189

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

#create_list(list_name, subject, template = 'discussion_list', description = ' ', topics = ' ') ⇒ Object Also known as: createList

Creates list list_name with subject subject. Returns boolean.

Raises:



253
254
255
256
 
# File 'lib/mail/sympa.rb', line 253

def create_list(list_name, subject, template='discussion_list', description=' ', topics=' ')
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'createList', [list_name, subject, template, description, topics])
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:



227
228
229
230
 
# File 'lib/mail/sympa.rb', line 227

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:



145
146
147
148
 
# File 'lib/mail/sympa.rb', line 145

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 }

Raises:



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

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)



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

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:



159
160
161
162
 
# File 'lib/mail/sympa.rb', line 159

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:



242
243
244
245
 
# File 'lib/mail/sympa.rb', line 242

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:



235
236
237
238
 
# File 'lib/mail/sympa.rb', line 235

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:



181
182
183
184
 
# File 'lib/mail/sympa.rb', line 181

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