.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::MtPolicyd::Cookbook::BasicPlugin 3pm"
.TH Mail::MtPolicyd::Cookbook::BasicPlugin 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::MtPolicyd::Cookbook::BasicModule \- how to write your own mtpolicyd plugin
.SH "VERSION"
.IX Header "VERSION"
version 2.05
.SH "How to write your own mtpolicyd plugin"
.IX Header "How to write your own mtpolicyd plugin"
mtpolicyd makes use of Moose. If you're not yet familiar with Moose you should start reading the Moose::Intro first.
.SS "Basic skeleton of a mtpolicyd plugin"
.IX Subsection "Basic skeleton of a mtpolicyd plugin"
A plugin in mtpolicyd is basically a class which inherits from Mail::MtPolicyd::Plugin and is located below the Mail::MtPolicyd::Plugin:: namespace:
.PP
.Vb 1
\&  package Mail::MtPolicyd::Plugin::HelloWorld;
\&
\&  use Moose;
\&  use namespace::autoclean;
\&
\&  # VERSION
\&  # ABSTRACT: a mtpolicyd plugin which just returns a hello world reject
\&
\&  extends \*(AqMail::MtPolicyd::Plugin\*(Aq;
\&
\&  use Mail::MtPolicyd::Plugin::Result;
\&
\&  sub run {
\&    my ( $self, $r ) = @_;
\&
\&    return Mail::MtPolicyd::Plugin::Result\->new(
\&      action => \*(Aqreject Hello World!\*(Aq,
\&      abort => 1,
\&    );
\&  }
\&
\&  _\|_PACKAGE_\|_\->meta\->make_immutable;
\&
\&  1;
.Ve
.PP
Every plugin must implement a \fBrun()\fR method. mtpolicyd will call \fBrun()\fR every time your module is called from the configuration to process a request.
A Mail::MtPolicyd::Request object containing the current request is passed to the method.
The \fBrun()\fR method must return undef or a <Mail::MtPolicyd::Plugin::Result> object.
If undef is return mtpolicyd will continue with the next plugin.
If a result is returned mtpolicyd will push the result to the list of results and abort processing the request if abort is set.
.PP
After you placed the module with your lib search path you should be able to use the plugin within mtpolicyd.conf:
.PP
.Vb 3
\&  <Plugin hello\-world>
\&    module = "HelloWorld"
\&  </Plugin>
.Ve
.PP
For now our plugin will just return an \*(L"reject Hello World!\*(R" action to the \s-1MTA.\s0
.SS "Adding configuration options"
.IX Subsection "Adding configuration options"
All options defined in the configuration file will be passed to the object constructor \fBnew()\fR when creating an object of your plugin class.
.PP
The parameter \*(L"module\*(R" is not passed to the object constructor because it contains the name of your class.
.PP
You can defined configuration parameters by adding attributes to your class.
.PP
You're class already inherits 3 attributes from the Plugin base class:
.IP "name (required)" 4
.IX Item "name (required)"
Which contains the name of your <Plugin> section.
.IP "log_level (default: 4)" 4
.IX Item "log_level (default: 4)"
Which contains the level used when your plugin calls \f(CW$self\fR\->log( \f(CW$r\fR, '...');.
.IP "on_error (default: undef)" 4
.IX Item "on_error (default: undef)"
Tells mtpolicyd what to do when the plugin dies.
.Sp
If set to \*(L"continue\*(R" mtpolicyd will continue processing and just leaves a line in the log.
.PP
Add a new attribute to your plugin class:
.PP
.Vb 1
\&  has \*(Aqtext\*(Aq => ( is => \*(Aqrw\*(Aq, isa => \*(AqStr\*(Aq, default => \*(AqHello World!\*(Aq);
.Ve
.PP
Return this string instead of the hard coded string:
.PP
.Vb 1
\&      action => \*(Aqreject \*(Aq.$self\->text,
.Ve
.PP
The string is now configurable from the configuration:
.PP
.Vb 4
\&  <Plugin hello\-world>
\&    module = "HelloWorld"
\&    text = "Hello Universe!"
\&  </Plugin>
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Markus Benning <ich@markusbenning.de>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2014 by Markus Benning <ich@markusbenning.de>.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU General Public License, Version 2, June 1991
.Ve