PMG/API2/Postfix.pm

   1 package PMG::API2::Postfix;
   2
   3 use strict;
   4 use warnings;
   5 use Data::Dumper;
   6
   7 use PVE::SafeSyslog;
   8 use PVE::Tools qw(extract_param);
   9 use PVE::JSONSchema qw(get_standard_option);
  10 use PVE::RESTHandler;
  11 use PVE::INotify;
  12
  13 use PMG::Postfix;
  14
  15 use base qw(PVE::RESTHandler);
  16
  17 my $postfix_queues = ['deferred', 'active', 'incoming', 'hold'];
  18
  19 my $queue_name_option = {
  20     description => "Postfix queue name.",
  21     type => 'string',
  22     enum => $postfix_queues,
  23 };
  24
  25 my $queue_id_option = {
  26     description => "The Message queue ID.",
  27     type => 'string',
  28     pattern => '[a-zA-Z0-9]+',
  29     minLength => 8,
  30     maxLength => 20,
  31 };
  32
  33 __PACKAGE__->register_method ({
  34     name => 'index',
  35     path => '',
  36     method => 'GET',
  37     permissions => { user => 'all' },
  38     description => "Directory index.",
  39     parameters => {
  40         additionalProperties => 0,
  41         properties => {
  42             node => get_standard_option('pve-node'),
  43         },
  44     },
  45     returns => {
  46         type => 'array',
  47         items => {
  48             type => "object",
  49             properties => {},
  50         },
  51         links => [ { rel => 'child', href => "{name}" } ],
  52     },
  53     code => sub {
  54         my ($param) = @_;
  55
  56         my $result = [
  57             { name => 'queue' },
  58             { name => 'qshape' },
  59             { name => 'flush_queues' },
  60             { name => 'discard_verify_cache' },
  61         ];
  62
  63         return $result;
  64     }});
  65
  66 __PACKAGE__->register_method ({
  67     name => 'qshape',
  68     path => 'qshape',
  69     method => 'GET',
  70     permissions => { check => [ 'admin', 'audit' ] },
  71     protected => 1,
  72     proxyto => 'node',
  73     description => "Print Postfix queue domain and age distribution.",
  74     parameters => {
  75         additionalProperties => 0,
  76         properties => {
  77             node => get_standard_option('pve-node'),
  78             queue => {
  79                 description => $queue_name_option->{description},
  80                 type => 'string',
  81                 enum => $postfix_queues,
  82                 default => 'deferred',
  83                 optional => 1,
  84             },
  85         },
  86     },
  87     returns => {
  88         type => 'array',
  89         items => {
  90             type => "object",
  91             properties => {},
  92         },
  93     },
  94     code => sub {
  95         my ($param) = @_;
  96
  97         my $queue = $param->{queue} || 'deferred';
  98
  99         my $res = PMG::Postfix::qshape($queue);
 100
 101         return $res;
 102     }});
 103
 104
 105 __PACKAGE__->register_method ({
 106     name => 'queue_index',
 107     path => 'queue',
 108     method => 'GET',
 109     permissions => { user => 'all' },
 110     description => "Directory index.",
 111     parameters => {
 112         additionalProperties => 0,
 113         properties => {
 114             node => get_standard_option('pve-node'),
 115         },
 116     },
 117     returns => {
 118         type => 'array',
 119         items => {
 120             type => "object",
 121             properties => {},
 122         },
 123         links => [ { rel => 'child', href => "{name}" } ],
 124     },
 125     code => sub {
 126         my ($param) = @_;
 127
 128         my $res = [];
 129         foreach my $queue (@$postfix_queues) {
 130             push @$res, { name => $queue };
 131         }
 132         return $res;
 133    }});
 134
 135 __PACKAGE__->register_method ({
 136     name => 'mailq',
 137     path => 'queue/{queue}',
 138     method => 'GET',
 139     permissions => { check => [ 'admin', 'audit' ] },
 140     protected => 1,
 141     proxyto => 'node',
 142     description => "List the mail queue for a specific domain.",
 143     parameters => {
 144         additionalProperties => 0,
 145         properties => {
 146             node => get_standard_option('pve-node'),
 147             queue => $queue_name_option,
 148             start => {
 149                 type => 'integer',
 150                 minimum => 0,
 151                 optional => 1,
 152             },
 153             limit => {
 154                 type => 'integer',
 155                 minimum => 0,
 156                 optional => 1,
 157             },
 158             filter => {
 159                 description => "Filter string.",
 160                 type => 'string',
 161                 maxLength => 64,
 162                 optional => 1,
 163             },
 164         },
 165     },
 166     returns => {
 167         type => 'array',
 168         items => {
 169             type => "object",
 170             properties => {},
 171         },
 172         links => [ { rel => 'child', href => "{queue_id}" } ],
 173      },
 174     code => sub {
 175         my ($param) = @_;
 176
 177         my $restenv = PMG::RESTEnvironment->get();
 178
 179         my ($count, $res) = PMG::Postfix::mailq(
 180             $param->{queue}, $param->{filter}, $param->{start}, $param->{limit});
 181
 182         $restenv->set_result_attrib('total', $count);
 183
 184         return $res;
 185     }});
 186
 187
 188 __PACKAGE__->register_method ({
 189     name => 'read_queued_mail',
 190     path => 'queue/{queue}/{queue_id}',
 191     method => 'GET',
 192     permissions => { check => [ 'admin' ] },
 193     protected => 1,
 194     proxyto => 'node',
 195     description => "Get the contents of a queued mail.",
 196     parameters => {
 197         additionalProperties => 0,
 198         properties => {
 199             node => get_standard_option('pve-node'),
 200             queue => $queue_name_option,
 201             queue_id => $queue_id_option,
 202             header => {
 203                 description => "Show message header content.",
 204                 type => 'boolean',
 205                 default => 1,
 206                 optional => 1,
 207             },
 208             body => {
 209                 description => "Include body content.",
 210                 type => 'boolean',
 211                 default => 0,
 212                 optional => 1,
 213             },
 214         },
 215     },
 216     returns => { type => 'string' },
 217     code => sub {
 218         my ($param) = @_;
 219
 220         $param->{header} //= 1;
 221
 222         return PMG::Postfix::postcat($param->{queue_id}, $param->{header}, $param->{body});
 223     }});
 224
 225 __PACKAGE__->register_method ({
 226     name => 'flush_queued_mail',
 227     path => 'queue/{queue}/{queue_id}',
 228     method => 'POST',
 229     permissions => { check => [ 'admin' ] },
 230     protected => 1,
 231     proxyto => 'node',
 232     description => "Schedule immediate delivery of deferred mail with the specified queue ID.",
 233     parameters => {
 234         additionalProperties => 0,
 235         properties => {
 236             node => get_standard_option('pve-node'),
 237             queue => $queue_name_option,
 238             queue_id => $queue_id_option,
 239         },
 240     },
 241     returns => { type => 'null' },
 242     code => sub {
 243         my ($param) = @_;
 244
 245         PMG::Postfix::flush_queued_mail($param->{queue_id});
 246
 247         return undef;
 248     }});
 249
 250 __PACKAGE__->register_method ({
 251     name => 'delete_queued_mail',
 252     path => 'queue/{queue}/{queue_id}',
 253     method => 'DELETE',
 254     permissions => { check => [ 'admin' ] },
 255     protected => 1,
 256     proxyto => 'node',
 257     description => "Delete one message with the named queue ID.",
 258     parameters => {
 259         additionalProperties => 0,
 260         properties => {
 261             node => get_standard_option('pve-node'),
 262             queue => $queue_name_option,
 263             queue_id => $queue_id_option,
 264         },
 265     },
 266     returns => { type => 'null' },
 267     code => sub {
 268         my ($param) = @_;
 269
 270         PMG::Postfix::delete_queued_mail($param->{queue}, $param->{queue_id});
 271
 272         return undef;
 273     }});
 274
 275
 276 __PACKAGE__->register_method ({
 277     name => 'delete_all_queues',
 278     path => 'queue',
 279     method => 'DELETE',
 280     description => "Delete all mails in all posfix queues.",
 281     proxyto => 'node',
 282     permissions => { check => [ 'admin' ] },
 283     protected => 1,
 284     parameters => {
 285         additionalProperties => 0,
 286         properties => {
 287             node => get_standard_option('pve-node'),
 288         },
 289     },
 290     returns => { type => 'null' },
 291     code => sub {
 292         my ($param) = @_;
 293
 294         PMG::Postfix::delete_queue();
 295
 296         return undef;
 297     }});
 298
 299 __PACKAGE__->register_method ({
 300     name => 'delete_queue',
 301     path => 'queue/{queue}',
 302     method => 'DELETE',
 303     description => "Delete all mails in the queue.",
 304     proxyto => 'node',
 305     permissions => { check => [ 'admin' ] },
 306     protected => 1,
 307     parameters => {
 308         additionalProperties => 0,
 309         properties => {
 310             node => get_standard_option('pve-node'),
 311             queue => $queue_name_option,
 312         },
 313     },
 314     returns => { type => 'null' },
 315     code => sub {
 316         my ($param) = @_;
 317
 318         PMG::Postfix::delete_queue($param->{queue});
 319
 320         return undef;
 321     }});
 322
 323
 324 __PACKAGE__->register_method ({
 325     name => 'flush_queues',
 326     path => 'flush_queues',
 327     method => 'POST',
 328     description => "Flush the queue: attempt to deliver all queued mail.",
 329     proxyto => 'node',
 330     permissions => { check => [ 'admin' ] },
 331     protected => 1,
 332     parameters => {
 333         additionalProperties => 0,
 334         properties => {
 335             node => get_standard_option('pve-node'),
 336         },
 337     },
 338     returns => { type => 'null' },
 339     code => sub {
 340         my ($param) = @_;
 341
 342         PMG::Postfix::flush_queues();
 343
 344         return undef;
 345     }});
 346
 347
 348 __PACKAGE__->register_method ({
 349     name => 'discard_verify_cache',
 350     path => 'discard_verify_cache',
 351     method => 'POST',
 352     description => "Discards the address verification cache.",
 353     proxyto => 'node',
 354     permissions => { check => [ 'admin' ] },
 355     protected => 1,
 356     parameters => {
 357         additionalProperties => 0,
 358         properties => {
 359             node => get_standard_option('pve-node'),
 360         },
 361     },
 362     returns => { type => 'null' },
 363     code => sub {
 364         my ($param) = @_;
 365
 366         PMG::Postfix::discard_verify_cache();
 367
 368         return undef;
 369     }});
 370
 371 1;