< Previous PageNext Page >

Hide TOC

Creating Mail Account Bundles

Starting with Mac OS X version 10.4, Mail has a new user interface for configuring accounts. The interface is a series of panels that prompts the user for information and verifies the information during the configuration process. You can provide users with a mail account bundle that streamlines the account setup process. Information such as the server name and connection options can be preset. Additionally, you can specify whether or not the user is allowed to change the values you have specified. There is also a setting that allows you to direct the user to a URL where they can get information to help with troubleshooting problems on their own. In this article, you will learn how to create a mail account bundle and you will see an example that is an excellent starting point for creating your own mail account bundles.

Creating a Bundle Directory

To create a mail account bundle, first create a new directory that will hold the files associated with the mail account bundle. To avoid name conflicts, the name of the mail account bundle directory should be the reverse-ordered ICANN domain name (for example, com.apple) and have the suffix mailaccounts. The bundle used to assist .mac users setting up mail accounts is installed in /Library/Mail/AccountTypes and is named com.mac.mailaccounts.

Next, create a XML file inside the bundle. It must be named MailAccounts.plist. This file should be an XML property list file with the keys listed in Table 1. All keys are required unless explicitly indicated as optional. See the example at the end of this document for the proper nesting of keys.

Note: Some of the dictionary keys have been deprecated in Mac OS X v10.5. These keys may still be used for mail account bundles in Mac OS X v10.4 but are ignored in Mac OS X v10.5.

**Table 1** Keys in `MailAccounts.plist`
Type	Description	Key
`AccountIconName` (deprecated)	String	Optional. The name of an icon file to use for this account. The icon should be 16 by 16 pixels and the file should be placed in the top level of the bundle directory.
`Accounts`	Array	An array of dictionary elements describing the account types. See “Account Dictionaries” for details on the format of these dictionaries.
`Identifier`	String	The reverse-ordered ICANN domain name; for example, `com.mac`. This name must be unique.
`Version`	Integer	Currently, the `version` value must be `1`.

Account Dictionaries

Each dictionary in the Accounts array describes an account type that can be configured by the user. The keys in Table 2are supported. Unless indicated as optional, all keys are required for each account dictionary defined in the property list.

**Table 2** Keys in each dictionary in `Accounts`
Key	Type	Description
`AccountID`	String	A CFUUID string, generated by running `uuidgen` in Terminal. For more information about CFUUIDs, see CFUUID Reference.
`AccountName`	String	The default account name for an account.
`AuthenticationScheme`	Array	Optional. An array of supported authentication schemes. An empty array or missing key causes accounts to be configured using `Password` security. List all authentication schemes that are supported by the account. The first item in the list is the preferred scheme. Supported schemes are: • `Password` • `CRAM-MD5` • `GSSAPI` • `KERBEROS_V4` (deprecated) • `X_KPOP` (deprecated) Both `KERBEROS_V4` and `X_KPOP` are now treated as `GSSAPI` in Mac OS X v10.5.
`AuthenticationSchemeIsEditable` (deprecated)	Boolean	Optional. Indicates whether the user is allowed to change the authentication scheme.
`DeliveryAccounts`	Array	Optional. This is an array of CFUUIDs associated with mail delivery accounts defined in the same mail account bundle. The first outgoing account defined in the array is used by default.
`EmailAddressDomain`	String	Optional. Indicates the domain name associated with the e-mail address. Mail uses this key to match the user's email address to the enclosing account dictionary.
`PortNumber`	Integer	Optional. A non-standard port number to use when connecting to the server. When specified, Mail attempts to connect to the port first before trying standard port numbers.
`PortNumberIsEditable` (deprecated)	Boolean	Optional. Indicates whether the user is allowed to change the port number used when connecting to the server.
`Protocol`	String	Indicates what protocol to use when communicating with the server. Supported values are: • `IMAP` • `POP` • `SMTP`
`SSLEnabled`	Boolean	Optional. Indicates whether SSL should be used when communicating with the server. If this key is not specified, Mail attempts an SSL connection to the server first and falls back to non-SSL if that fails.
`SSLEnabledIsEditable` (deprecated)	Boolean	Optional. Indicates whether the user is allowed to change the setting of whether SSL is used or not. If this key is set to true and Mail fails to connect to the server using SSL, the user is shown the Incoming Security Settings pane of the setup assistant.
`ServerName`	Array	A list of server names to allow the user to pick from. The first server name is the preferred server and is used by default.
`ServerNameIsEditable` (deprecated)	Boolean	Optional. Indicates whether the user is allowed to change the server name.
`SupportURL`	String	Optional. The URL shown in the Mail Account Preferences panel that takes the user to the specified webpage for more help or information.
`SupportURLLabel`	String	Optional. When present, the specified value is displayed instead of the `SupportURL` value in the Mail account preference panel. Clicking on the label opens the URL stored in `SupportURL`.
`UserNameIsEmailAddress`	Boolean	Optional. Indicates whether the user name is the user’s full email address.
`UserNameMatchesEmailAddress`	Boolean	Optional. Indicates whether the user name and the portion of the user's email address to the left of the @ sign are the same value.

Localizing Mail Accounts

You can localize values for the AccountName and SupportURL keys in mail account bundles. This lets each account have its own localizations. For more information on localization, see the Internationalization Documentation.

Using Simplified Account Setup

Mail provides a new feature in Mac OS X v10.5 that allows users to add a new account with only their full name, email address, and password. This feature is known as simplified account setup.

Mail account bundles are automatically used for simplified account setup if the following conditions are met:

The EmailAddressDomain dictionary key must be specified.
The UserNameIsEmailAddress or UserNameMatchesEmailAddress dictionary key must be set to true.
The DeliveryAccounts dictionary key must have exactly one CFUUID.

Installation

To install a mail account bundle, you need to place the top-level directory, which contains the MailAccount.plist file, in one of the following locations:

~/Library/Mail/AccountTypes
/Library/Mail/AccountTypes
/Network/Library/Mail/AccountTypes

A Mail Bundle Property List Example

The following example is the property list used to create the .Mac mail account bundle shipping with Mac OS X v10.4 and later:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>Accounts</key>

    <array>

        <dict>

            <key>AccountID</key>

            <string>5D795DD4-55CB-11D8-A81E-000A957054BE</string>

            <key>AccountName</key>

            <string>.Mac</string>

            <key>AuthenticationScheme</key>

            <array>

            <array/>

            <key>DeliveryAccounts</key>

            <array>

                <string>5C5150FA-55CB-11D8-A746-000A957054BE</string>

            </array>

            <key>EmailAddressDomain</key>

            <string>@mac.com</string>

            <key>Protocol</key>

            <string>IMAP</string>

            <key>ServerName</key>

            <array>

                <string>mail.mac.com</string>

            </array>

            <key>UserNameMatchesEmailAddress</key>

            <true/>

        </dict>

        <dict>

            <key>AccountID</key>

            <string>5C5150FA-55CB-11D8-A746-000A957054BE</string>

            <key>AccountName</key>

            <string>.Mac SMTP</string>

            <key>AuthenticationScheme</key>

            <array>

                <string></string>

            </array>

            <key>Protocol</key>

            <string>SMTP</string>

            <key>ServerName</key>

            <string>smtp.mac.com</string>

        </dict>

    </array>

    <key>Identifier</key>

    <string>com.mac</string>

    <key>Version</key>

    <integer>1</integer>

</dict>

</plist>