NAME

Podius::EmailOperations - useful email-related operations

SYNOPSIS

  use Podius::EmailOperations;

  my $email = 'some@where.com';
  die "Invalid email address $email\n"
      unless is_valid_email_address($email);

  send_email(
      $email, real_name => "Adam Roy", from => 'Me <me@here.com>',
      subject => undef,  # take Subject: line from content
      content => "Subject: Confirm order\n\nHello, {real_name}\n",
  );

  # Now some usuful confirmation functionality

  # in register.cgi
  send_confirmation_email(
      "registration", $email, "confirm_registration.cgi",
      first_name => "Adam", last_name => "Smith",
      content_locale_key => 'request-registration-confirmation',
  );

  # in confirm_registration.cgi
  my ($stored_key, %stored_params) =
      get_confirmation_data("registration", $email);
  my $entered_key = CGI::param("confirmation_key");
  die "Invalid confirmation key\n" unless $stored_key eq $entered_key;

  # optional
  remove_confirmation_file("registration", $email);

DESCRIPTION

This is a collection of convenient email-related functions useful for web-based projects that require email interaction with a user.

FUNCTIONS

is_valid_email_address email: Return true if the given email corresponds to the specification.
send_email email params_hash: Sends an email with the given parameters to email address (or to several addresses if email is arrayref or comma-or-semicolon-delimited string).; Note, you should specify one of the mandatory parameters, either ``content'' (the email body text) or ``content_filename'' (that may be absolute or relative to PROJECT_HOME) or ``content_template_name'' (that may be absolute or relative to TEMPLATE_HOME, see the Podius::Template manpage) or ``content_locale_key'' (then the content is taken from the podius-locale based translations).; Note, if $Podius::PROJECT_HOME and/or $Podius::PROJECTS_HOME defined (that is the case after ``use Podius;'') then leading ``~'' like ``~/dir/file'' and/or ``~project/dir/file'' in ``content_filename'' and ``content_template_name'' is expanded accourdingly.; The From: and Subject: values may be specified as ``from'' and ``subject'' parameters or may be given as the headers in the first two or less lines in the ``content''. Also ``fallback_from'' and ``fallback_subject'' parameters are supported that are only used if no corresponding headers are found.; If the optional ``real_name'' (or ``first_name'' and ``last_name''; or ``nick'') parameters are passed in params_hash, they are used to build the recipient name that is used together with email in To: header (and they may be interpolated in the body just like other params). If none of these are specified, then the recepient name is taken to be ``Visitor''.; If however multiple email addresses are given, then they are just used as is in To: without constructed ``real_name'' added.; All ``*_url'' parameters are normalized for interpolation to create a full url if needed.; If flag ``use_podius_template'' or ``content_template_name'' parameter is specified, then the content is parsed like a normal Podius::Template template with the params_hash reference being the initial operand, i.e. <{topic}> <{real_name &htmlize}>.; Otherwise the content is a simple template with ``{name}'' interpolations, that are taken from params_hash.; The Content-Type email header defaults to 'text/plain; charset=utf-8', but can be explicitly set in ``content_type'' parameter.
get_confirmation_data topic email: Returns previously issued and saved confirmation key and the additional parameter hash (if any) for the given topic and email.; The issued confirmation key together with the corresponding parameters is stored in a file in the special project's subdirectory. The error is raised if it does not exist or not writable.
get_confirmation_key topic email: This is just a convenient shortcut for get_confirmation_data, only the first element is returned.
get_confirmation_params topic email: This is just a convenient shortcut for get_confirmation_data, all but the first element are returned.
send_confirmation_email topic email uri params_hash: Issues a random confirmation key and sends it to the given email.; Note, you should specify one of the mandatory parameters, either ``content'' or ``content_locale_key'' (in the last case the contents is taken from the podius-locale based translations).; If the optional ``real_name'' (or ``first_name'' and ``last_name''; or ``nick_name'') parameters are passed in params_hash, they are used in the body and the recipient of the sent message.; The issued confirmation key together with the corresponding params_hash is stored in a file in the special project's subdirectory. The error is raised if it does not exist or not writable.
remove_confirmation_file topic email: Removes the saved confirmation file for the given topic and email.; This function does not fail, returns true if the file was removed.