class Mail::Sympa

The Sympa module encapsulates the various Sympa server SOAP methods

Constants

VERSION

The version of the mail-sympa library.

Attributes

endpoint[R]

The endpoint URL of the SOAP service.

namespace[R]

The URN namespace. The default is 'urn:sympasoap'.

url[R]

The endpoint URL of the SOAP service.

Public Class Methods

new(endpoint, namespace = 'urn:sympasoap') click to toggle source

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')
# 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

Public Instance Methods

add(email, list_name, name, quiet=true) click to toggle source

Adds the given email to list_name using name (gecos). If quiet is set to true (the default) then no email notification is sent.

# 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
amI(user, list_name, function = 'editor')
Alias for: am_i?
am_i?(user, list_name, function = 'editor') click to toggle source

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

# 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
Also aliased as: amI
authenticateRemoteAppAndRun(app_name, app_password, variables, service, parameters)
authenticate_remote_app_and_run(app_name, app_password, variables, service, parameters) click to toggle source

Run command in trusted context.

# 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
Also aliased as: authenticateRemoteAppAndRun
closeList(list_name)
Alias for: close_list
close_list(list_name) click to toggle source

Closes list list_name. Returns boolean.

# 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
Also aliased as: closeList
complexLists(topic='', sub_topic='')
Alias for: complex_lists
complexWhich(user, app_name, app_passwd)
Alias for: complex_which
complex_lists(topic='', sub_topic='') click to toggle source

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.login(email, password)

sympa.complex_lists.each{ |list|
  puts list.subject
  puts list.homepage
}
# 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
Also aliased as: complexLists
complex_which(user, app_name, app_passwd) click to toggle source

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

# 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
Also aliased as: complexWhich
createList(list_name, subject, template='discussion_list', description=' ', topics=' ')
Alias for: create_list
create_list(list_name, subject, template='discussion_list', description=' ', topics=' ') click to toggle source

Creates list list_name with subject subject. Returns boolean.

# 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
Also aliased as: createList
del(email, list_name, quiet=true) click to toggle source

Deletes the given email from list_name. If quiet is set to true (the default) then no email notification is sent.

# 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
Also aliased as: delete
delete(email, list_name, quiet=true)
Alias for: del
info(list_name) click to toggle source

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

Example:

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

info = sympa.info(list)

puts info.subject
puts info.homepage
puts info.isOwner
# 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='') click to toggle source

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.login(email, password)

sympa.lists.each{ |list| puts list }
# 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) click to toggle source

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.login(email, password)
# File lib/mail/sympa.rb, line 85
def login(email, password)
  @email    = email
  @password = password
  @cookie   = @soap.login(email, password)
end
review(list_name) click to toggle source

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

Example:

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

sympa.review(list)
# 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) click to toggle source

Removes the currently logged in user from list_name.

# 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
Also aliased as: unsubscribe
subscribe(list_name, name = @email) click to toggle source

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

# 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
unsubscribe(list_name)
Alias for: signoff
which(user, app_name, app_passwd) click to toggle source

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.login(email, password)

# If vars contains USER_EMAIL
sympa.which('USER_EMAIL=some_user@foo.com', 'my_app', 'my_password')

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

# 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