apple_device-management/declarative/declarations/configurations/account.mail.yaml

title: Account:Mail
description: The declaration to configure a Mail account.
payload:
  declarationtype: com.apple.configuration.account.mail
  supportedOS:
    iOS:
      introduced: '15.0'
      allowed-enrollments:
      - supervised
      - device
      - user
      - local
      allowed-scopes:
      - system
      sharedipad:
        allowed-scopes:
        - user
    macOS:
      introduced: '13.0'
      allowed-enrollments:
      - supervised
      - user
      - local
      allowed-scopes:
      - user
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '1.1'
      allowed-enrollments:
      - supervised
      - device
      - user
      - local
      allowed-scopes:
      - system
    watchOS:
      introduced: n/a
  apply: multiple
payloadkeys:
- key: VisibleName
  title: Account name
  type: <string>
  presence: optional
  content: The name that apps show to the user for this mail account. If not present,
    the system generates a suitable default.
- key: UserIdentityAssetReference
  title: User identity asset reference
  type: <string>
  assettypes:
  - com.apple.asset.useridentity
  presence: optional
  content: The identifier of an asset declaration that contains the user identity
    for this account. Set the corresponding asset type to `UserIdentity`.
- key: IncomingServer
  title: Incoming server settings
  type: <dictionary>
  presence: required
  content: The settings for the incoming mail server for this account.
  subkeys:
  - key: ServerType
    title: Server type
    type: <string>
    presence: required
    rangelist:
    - IMAP
    - POP
    content: The mail protocol this account uses.
  - key: HostName
    title: Server host name
    type: <string>
    presence: required
    content: The host name for the incoming mail server.
  - key: Port
    title: Server port
    type: <integer>
    presence: optional
    content: The port number for the incoming mail server.
  - key: AuthenticationMethod
    title: Server authentication method
    type: <string>
    presence: required
    rangelist:
    - None
    - Password
    - CRAMMD5
    - NTLM
    - HTTPMD5
    content: The authentication method for the incoming mail server.
  - key: AuthenticationCredentialsAssetReference
    title: Authentication credentials asset reference
    type: <string>
    assettypes:
    - com.apple.asset.credential.userpassword
    presence: optional
    content: |-
      The identifier of an asset declaration that contains the credentials for this account to authenticate with an incoming mail server. The corresponding asset must be of type `CredentialUserNameAndPassword`.

      If the `AuthenticationMethod` is `None`, this field must be blank. Otherwise, the declaration must contain this field.
  - key: IMAPPathPrefix
    title: IMAP path prefix
    type: <string>
    presence: optional
    content: The path prefix for the IMAP server. The system uses this only when `ServerType`
      is `IMAP`.
- key: OutgoingServer
  title: Outgoing server settings
  type: <dictionary>
  presence: required
  content: The settings for the outgoing mail server for this account.
  subkeys:
  - key: HostName
    title: Server host name
    type: <string>
    presence: required
    content: The host name for the outgoing mail server.
  - key: Port
    title: Server port
    type: <integer>
    presence: optional
    content: The port number for the outgoing mail server.
  - key: AuthenticationMethod
    title: Server authentication method
    type: <string>
    presence: required
    rangelist:
    - None
    - Password
    - CRAMMD5
    - NTLM
    - HTTPMD5
    content: The authentication method for the outgoing mail server.
  - key: AuthenticationCredentialsAssetReference
    title: Authentication credentials asset reference
    type: <string>
    assettypes:
    - com.apple.asset.credential.userpassword
    presence: optional
    content: |-
      The identifier of an asset declaration that contains the credentials for this account to authenticate with an outgoing mail server. The corresponding asset must be of type `CredentialUserNameAndPassword`.

      If the `AuthenticationMethod` is `None`, this field must be blank. Otherwise, the declaration must contain this field.
- key: SMIME
  title: S/MIME settings
  supportedOS:
    iOS:
      introduced: '17.0'
    macOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: Settings for S/MIME.
  subkeys:
  - key: Signing
    title: S/MIME signing settings
    type: <dictionary>
    presence: optional
    content: Settings for S/MIME signing.
    subkeys:
    - key: Enabled
      title: Signing enabled
      type: <boolean>
      presence: required
      content: If `true`, the system enables S/MIME signing.
    - key: IdentityAssetReference
      title: S/MIME signing identity asset reference
      type: <string>
      assettypes:
      - com.apple.asset.credential.acme
      - com.apple.asset.credential.identity
      - com.apple.asset.credential.scep
      presence: optional
      content: Specifies the identifier of an asset declaration containing the identity
        required for S/MIME signing of messages sent from this account.
    - key: UserOverrideable
      title: Signing user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can turn S/MIME signing on or off in Settings.
    - key: IdentityUserOverrideable
      title: Signing identity user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can select an S/MIME signing identity in Settings.
  - key: Encryption
    title: S/MIME encryption settings
    type: <dictionary>
    presence: optional
    content: Settings for S/MIME encryption.
    subkeys:
    - key: Enabled
      title: Encryption by default enabled
      type: <boolean>
      presence: required
      content: If `true`, the system enables S/MIME encryption by default, which the
        user can't override if `PerMessageSwitchEnabled` is `false`.
    - key: IdentityAssetReference
      title: S/MIME encryption identity asset reference
      type: <string>
      assettypes:
      - com.apple.asset.credential.acme
      - com.apple.asset.credential.identity
      - com.apple.asset.credential.scep
      presence: optional
      content: Specifies the identifier of an asset declaration containing the identity
        required for S/MIME encryption. The system attaches the public certificate
        to outgoing mail to allow the user to receive encrypted mail. When the user
        sends encrypted mail, the system uses the public certificate to encrypt the
        copy of the mail in their Sent mailbox.
    - key: UserOverrideable
      title: Encryption by default user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can set the default value for S/MIME encryption
        to on or off in Settings.
    - key: IdentityUserOverrideable
      title: Encryption identity user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can select an S/MIME signing identity in Settings.
    - key: PerMessageSwitchEnabled
      title: Per message switch enabled
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the system enables the per-message encryption switch in
        the compose view.
related-status-items:
- status-items:
  - account.list.mail.incoming
  - account.list.mail.outgoing
  note: Each configuration will have a corresponding status item for incoming and
    outgoing accounts.
examples:
- title: Configuration example
  files:
  - description: This configuration sets up an IMAP email account with SMTP outgoing
      mail.
    file: examples/declarative/declarations/configurations/account.mail/example1.json