NAME

Synapse::MailSender - email notification system

About Synapse's Open Telephony Toolkit

Synapse::MailSender is a part of Synapse's Wholesale Open Telephony Toolkit.

As we are refactoring our codebase, we at Synapse have decided to release a substantial portion of our code under the GPL. We hope that as a developer, you will find it as useful as we have found open source and CPAN to be of use to us.

What is Synapse::MailSender all about

Wether it's to send rate notifications, QOS alarms, rate import confirmation, or credit limit warnings, doing wholesale telecom requires sending mail. Lots of mail, in fact.

The goal of this module is to provide a simple and easy to work with email sending library as well as a templating library. It is based on MIME::Lite to construct the mail and send it, and on Petal::Tiny and XML::Parser::REX to provide an XML email templating framework.

This modules allows you to constructs emails which have:

- an optional 'SetSender' attribute (set to 'From' by default)

- a 'From' field

- a 'To' field

- one or more optional 'Cc' (carbon copy) fields

- one or more optional 'Bcc' (blind carbon copy) fields

- a subject field

- One or more paragraphs, which will make up for the email contents, which is ALWAYS pure text. This module is designed for boring and dull email notifications.

- One or more optional file attachments, since it is useful for doing things like attaching PDF invoices, Excel spreadsheets with statistics, or cdr files in .CSV format for instance.

A simple example:

Say you have template.xml:

    <xml>
      <From petal:content="yaml/From">From</From>
      <To petal:content="yaml/To">To</To>
      <Subject petal:content="yaml/Subject">Subject</Subject>
      <Say>Hello, World</Say>
    </xml>

And somedata.yaml

    ---
    From: foo@bar.net
    To: baz@buz.com
    Subject: foo bar baz buz

You can use the provided script synapse-mailsender and type in the following command to have your email sent out:

    synapse-mailsender ./template.xml ./somedata.yaml

API

$class->new();

Creates a new Synapse::Mail::Sender object.

$self->Sendmail ('/usr/local/bin/mysendmail');

Sets the sendmail command to use with MIME::Lite. By default, is set to /usr/sbin/sendmail.

$self->From ('from@example.com');

Sets the 'From' field.

$self->To ('to@example.com');

Sets the 'To' field.

$self->Cc ('cc@example.com');

Adds a carbon copy recipient. Can be invoked multiple times to add more than one carbon copy recipients.

$self->Bcc ('cc@example.com');

Adds a 'blind carbon copy' recipient. Can be invoked multiple times to add more than one blind carbon copy recipients.

$self->Subject ('Your account is over limit');

Sets the 'Subject' field.

$self->SetSender ('Your account is over limit');

Sets the 'SetSender' field. If not set, the 'From' field will be used, which is what you want most of the time anyways.

$self->Body ('Dear Customer');

Adds a paragraph to the text body. i.e. you can call this method once per paragraph.

$self->Say ('Dear Customer');

Alias for Body(), looks nicer in templates.

$self->Para ('Dear Customer');

Another alias for Body(), can't make up my mind right now...

$self->Attach ('/path/to/file.xls');

Attaches a file to the message.

$self->loadxml ($path_to_xml_template, option1 => $option1, option2 => $option2, etc)

Uses Petal::Tiny to process $path_to_xml_template. Passes the following arguments to the template:

self : current Synapse::MailSender object

anything else you pass to it, i.e. in this case 'option1' and 'option2'.

Say your code looks like this:

    my $sMailSender = Synapse::MailSender->new();
    $sMailSender->loadxml ( '/opt/templates/accountsuspended.xml',
                            user => $user,
                            accountDetailsFile => $user->accountFile() );
    $sMailSender->send();

Your template itself may look roughly like this:

    <Message>
      <From petal:condition="true:user/from" petal:content="user/from">example@example.com</From>
      <To petal:condition="true:user/to" petal:content="user/to">example@example.com</To>
      <Cc petal:condition="true:user/cc" petal:repeat="cc user/cc" petal:content="cc">example@example.com</Cc>
      <Bcc petal:condition="true:user/bcc" petal:repeat="bcc user/bcc" petal:content="bcc">example@example.com</Bcc>
      <Subject>Your account is over limit</Subject>
      <Say>Dear Customer,</Say>
      
      <Say>Unfortunately, your account with a balance of <span petal:replace="user/balance">0.00</span>
      has reached its allowed limit.</Say>
      <Say>Your services are being suspended for now. We kindly request that you post a payment with us
      so that your account reaches its allowed credit limit.</Say>
      <Say>Get in touch.
Cheers
Ourselves (example@example.com)</Say>
      <Attach petal:condition="true:accountDetailsFile" petal:content="true:accountDetailsFile">some-file.xls</Attach>
    </Message>

$self->loadxml ($path_to_xml_template, $yamlfile)

Same as above, but passes a YAML file as options for template processing. The Dumped YAML is passed as 'yaml' in the template. option1 => $option1, option2 => $option2, etc)

$self->loadxml ($xmldata, option1 => $option1, option2 => $option2, etc)

Same as above, but instead of passing an XML Template name, the XML template data is passed directly.

$self->loadxml ($xmldata, $yamlfile)

Spame as above, but instead of passing an XML Template name, the XML template data is passed directly.

Plus, passes a YAML file as options for template processing. The Dumped YAML is passed as 'yaml' in the template. option1 => $option1, option2 => $option2, etc)

$self->message();

Once you have configured your Synapse::MailSender object with the methods above, you can construct a MIME::Lite object by invoking $self->message();

$self->send();

Once you have configured your Synapse::MailSender object with the methods above, you can send the corresponding email message using this method.

EXPORTS

none.

BUGS

Please report them to me. Patches always welcome...

AUTHOR

Jean-Michel Hiver, jhiver (at) synapse (dash) telecom (dot) com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Synapse::MailSender

perl -MCPAN -e shell
install Synapse::MailSender