From BRTT
How can I use Antelope to handle automatic emails?
Many times in distributed near-real-time systems, information of interest from external organizations is provided in the form of automated emails. When it is not possible or desirable to prevail upon all parties to engineer a more integrated data-exchange strategy, often it is nice at least to be able to handle these incoming emails in an automated manner. The mail_parser(1) and related utilities from the Antelope contributed-code repository help support this.
N.B. DISCLAIMER: All mail handling utilities in the Antelope contributed-code repository are provided as-is, with no guarantee either express or implied that they will function as desired, as described, or as expected. All risk of loss or difficulty of any sort from running these utilites is assumed solely by the end user.
The mail_parser(1) utility and its companion mail_parser_wrapper(1) are documented in the Antelope man pages, along with several customized handlers that already exist (for example submit_pepp(3), reb_import(3), pgc_pickfile(3), cnsn_pick(3), and mp_filemail(3)). The following text describes how to write a new handler.
First, the new module needs a name: we'll use "myimport". The simplest handler would be as follows: namely, a file called myimport.pl defining a perl function myimport_handler:
Contents |
See also
</noinclude> Note that the subroutine MUST be named as shown, with a "_handler" suffix appended to the name of the handler. Corresponding to this handler will be an entry in the mail_parser.pf parameter file:
See also
</noinclude> This particular example takes each incoming email and cleverly does absolutely nothing with it.
To make things more interesting, let's prepare the handler so it can save information of interest to a database. Say for example that we have designed a schema called Mystuff1.0 to hold any parsed information. As described in the man page for mail_parser, any 'extra' parameters in the mail_parser.pf for this handler will be given directly to the handler routine. Thus we can add the database name and the schema name to the entry in mail_parser.pf for this handler:
See also
</noinclude> These new parameters are available in our handler (myimport_handler) as follows:
See also
</noinclude> This pattern may be copied to add in any other parameters of interest for our customized handler. Now let's expand the handler to create and open the database:
See also
</noinclude> Finally, we need the handler to actually do something. The body of the email is available inside the handler as the array
See also
</noinclude> which can be parsed like any other perl array. For further information on what that $message object is and what you can do with it, see the man page on Mail::Internet(3). Anyway, let's say our schema has a table called "stuff" with fields "item" and "thing". The final handler will then look something like this:
See also
</noinclude> Next, a requirement if this is going to be submitted to contrib (and a strongly recommended idea in any case), the handler needs a man page:
See also
</noinclude> after which myimport.3p should be filled in according to the instructions in the comments.
Finally, this handler needs to be installed with an Antelope Makefile (see the man page antelopemakefile(5) for details) containing:
See also
</noinclude> which is invoked by
See also
</noinclude> After properly setting up mail_parser_wrapper, .forward, and possibly .procmailrc for the receiving account (see the man page for mail_parser_wrapper(1)), incoming email should be filtered and processed by the new handler. If all goes well, incoming emails should be parsed and the contents inserted into the database named myimports_db.