NAME
XML::AppleConfigProfile::Payload::Email - The Email payload type.
SYNOPSIS
use XML::AppleConfigProfile;
use XML::AppleConfigProfile::Payload::Email;
my $email = new XML::AppleConfigProfile::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 XML::AppleConfigProfile::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 XML::AppleConfigProfile::Payload::Exchange::iOS or XML::AppleConfigProfile::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 XML::AppleConfigProfile::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:
EmailAddressThis must be a properly-formed email address.
EmailAccountTypeThis must be the string
EmailTypePOPorEmailTypeIMAP.IncomingMailServerHostNameandOutgoingMailServerHostNameThese must be properly-formed hostnames or IP addresses (IPv4 or IPv6).
IncomingMailServerPortNumberandOutgoingMailServerPortNumberThese must be positive numbers less than 65535.
IncomingMailServerAuthenticationandOutgoingMailServerAuthenticationThese must be the string
EmailAuthPasswordorEmailAuthNone.All other payload keys will be checked as usual by the parent class.
See also the documentation in XML::AppleConfigProfile::Payload::Common.
PAYLOAD KEYS
All of the payload keys defined in XML::AppleConfigProfile::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.
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 XML::AppleConfigProfile 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.