/ 
Config-Apple-Profile-v0.87.1-TRIAL
River stage zero No dependents
/ Config::Apple::Profile::Payload::Email

NAME

Config::Apple::Profile::Payload::Email - The Email payload type.

SYNOPSIS

use Config::Apple::Profile;
use Config::Apple::Profile::Payload::Email;

my $email = new Config::Apple::Profile::Payload::Email;
my $payload = $email->payload;

$payload->{EmailAccountDescription} = 'Example Email';
$payload->{EmailAccountName} = 'Simon Blarfingar';
$payload->{EmailAddress} = 'user@example.com';
$payload->{EmailAccountType} = 'EmailTypeIMAP';

$payload->{IncomingMailServerHostName} = 'mail.example.com';
$payload->{OutgoingMailServerHostName} = $payload->{IncomingMailServerHostName};

$payload->{IncomingMailServerAuthentication} = 'EmailAuthPassword';
$payload->{OutgoingMailServerAuthentication} = $payload->{IncomingMailServerAuthentication};

$payload->{IncomingMailServerUsername} = $payload->{EmailAddress};
$payload->{OutgoingMailServerUsername} = $payload->{IncomingMailServerUsername};

$payload->{OutgoingPasswordSameAsIncomingPassword} = 1;
$payload->{SMIMEEnabled} = 1;

my $profile = new Config::Apple::Profile::Profile;
push @{$profile->content}, $email;

print $profile->export;

DESCRIPTION

This class implements the Email payload, which is used to configure POP and IMAP accounts. For Exchange accounts, refer to Config::Apple::Profile::Payload::Exchange::iOS or Config::Apple::Profile::Payload::Exchange::OSX.

Each email account has basic information, information about how to fetch mail, information about how to send mail, S/MIME configuration, and interaction.

For fetching mail, either POP or IMAP can be used. Authentication is with a password, or it can be turned off. SMTP is used for sending mail, either with or without a username and password. SSL is supported for both sending and receiving, and is enabled by default.

NOTE: If the server(s) are only accessible on an internal network, you may want to include a VPN payload as part of the profile, so that the user will be able to access the server(s) while not on the internal Wi-Fi network.

Passwords can be included in the payload, but then the payload should be encrypted, or delivered in some secure manner. If passwords are not specified, the user will be prompted to enter the password when the profile is installed.

S/MIME can be configured for email signing and decryption. For S/MIME to work, a .p12 file (a private key and certificate in a PKCS#12 container, also known as an "identity certificate") must be on the device. The identity certificate can be loaded using Config::Apple::Profile::Payload::Certificate::PKCS12, and may be part of the same profile, or a different profile. If S/MIME is enabled but no signing or decrypting certificates are specified in the payload, the user will be able to choose which identity certificate to use.

INSTANCE METHODS

The following instance methods are provided, or overridden, by this class.

validate_key($key, $value)

Performs additional validation for certain payload keys in this class:

  • EmailAddress

    This must be a properly-formed email address.

  • EmailAccountType

    This must be the string EmailTypePOP or EmailTypeIMAP.

  • IncomingMailServerHostName and OutgoingMailServerHostName

    These must be properly-formed hostnames or IP addresses (IPv4 or IPv6).

  • IncomingMailServerPortNumber and OutgoingMailServerPortNumber

    These must be positive numbers less than 65535.

  • IncomingMailServerAuthentication and OutgoingMailServerAuthentication

    These must be the string EmailAuthPassword or EmailAuthNone.

    All other payload keys will be checked as usual by the parent class.

See also the documentation in Config::Apple::Profile::Payload::Common.

PAYLOAD KEYS

All of the payload keys defined in Config::Apple::Profile::Payload::Common are used by this payload.

This payload has the following additional keys:

Basic account information

EmailAccountDescription

Optional

A string. This is the account description shown in the Mail and Settings apps.

EmailAccountName

Optional

The sender's name, shown in outgoing email addresses.

EmailAddress

Optional

The sender's full email address. If not provided, the user will be asked for it during installation.

Fetching mail

EmailAccountType

The type of email account. This is a string, either EmailTypePOP or EmailTypeIMAP.

CncomingMailServerHostName

The host name or IP address used for fetching mail.

IncomingMailServerPortNumber

Optional

The port number used for fetching mail. If not specified, the default port will be used.

IncomingMailserverUseSSL

Optional

A Boolean, which defaults to true. If true, use SSL when fetching mail.

IncomingMailServerAuthentication

The authentication method for fetching mail. Allowed strings are EmailAuthPassword and EmailAuthNone.

IncomingMailServerUsername

Optional

The username to use when fetching mail. If a string is not provided, but authentication is used, the user will be asked for it during installation.

IncomingPassword

Optional

The password to use when fetching mail. If a string is not provided, but authentication is used, the user may be asked for it during installation.

WARNING: This is private information. If this payload key is set, then the profile should be delivered to the user in a secure way.

Sending Mail

OutgoingMailServerHostName

The host name or IP address used for sending mail.

OutgoingMailServerPortNumber

Optional

The port number used for sending mail. If not specified, ports 25, 587, and 465, in that order, will be tried.

OutgoingMailserverUseSSL

Optional

A Boolean, which defaults to true. If true, use SSL when fetching mail.

OutgoingMailServerAuthentication

The authentication method for sending mail. Allowed strings are EmailAuthPassword and EmailAuthNone.

OutgoingMailServerUsername

Optional

The username to use when sending mail. If a string is not provided, but authentication is used, the user will be asked for it during installation.

OutgoingPassword

Optional

The password to use when sending mail. If a string is not provided, but authentication is used, the user may be asked for it during installation.

WARNING: This is private information. If this payload key is set, then the profile should be delivered to the user in a secure way.

OutgoingPasswordSameAsIncomingPassword

Optional

A Boolean, defaults to false. If no passwords have been set in the profile, but passwords are in use, and this key is true, then the user will be asked for a password once, and that one password will be used for fetching and sending mail.

S/MIME

SMIMEEnabled

Optional

A Boolean. If true, this account supports S/MIME. Defaults to false.

SMIMESigningCertificateUUID

Optional

The UUID of the PKCS12 Certificate payload used to sign emails.

SMIMEEncryptionCertificateUUID

Optional

The UUID of the PKCS12 Certificate payload used to decrypt emails.

SMIMEEnablePerMessageSwitch

Optional

A Boolean. If true, users will be able to disable S/MIME on emails they send. If false, S/MIME signing will be used for all emails, and S/MIME encryption will be used whenever possible.

Default is false.

Available in iOS 8.0 and later only.

Application Interaction

PreventMove

Optional

A Boolean. If true, messages may not be moved to other email accounts, and forwarding/replying from other accounts is prohibited. Defaults to false.

This payload key only applies to iOS 5.0 and later.

PreventAppSheet

Optional

A Boolean. If true, 3rd-party applications may not use this account to send mail. Defaults to false.

This payload key only applies to iOS 5.0 and later.

disableMailRecentsSyncing

Optional

A Boolean. If true, this account is excluded from syncing recently-used addresses. Defaults to false.

This payload key only applies to iOS 6.0 and later.

PayloadType

This is fixed to the string com.apple.mail.managed.

PayloadVersion

This is fixed to the value 1.

ACKNOWLEDGEMENTS

Refer to Config::Apple::Profile for acknowledgements.

AUTHOR

A. Karl Kornel, <karl at kornel.us>

COPYRIGHT AND LICENSE

Copyright © 2014 A. Karl Kornel.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.