voicemail.conf Core Settings and Mailbox Options

The voicemail.conf file defines voicemailAsterisk's built-in voice messaging system (app_voicemail), configured in voicemail.conf with mailboxes per user. behavior, mailbox accounts, message limits, recording formats, notifications, password policy, and spoken timezone formats. This page covers the settings most installations need and highlights options that can affect message retention or storage.

For the complete call flow, including VoiceMail(), VoiceMailMain(), PJSIPThe modern SIP channel driver in Asterisk (chan_pjsip), replacing the older chan_sip. Configured in pjsip.conf using endpoints, AORs, auths, and transports. MWI, and dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition → examples, start with Setting Up Voicemail in Asterisk.

Safe baseline

[general]
format = wav
serveremail = asterisk@example.com
attach = yes
mailcmd = /usr/sbin/sendmail -t
maxmsg = 100
maxsecs = 180
minsecs = 3
maxsilence = 0
silencethreshold = 128
maxlogins = 3
maxgreet = 60
minpassword = 6

[zonemessages]
eastern = America/New_York|'vm-received' Q 'digits/at' IMp
central = America/Chicago|'vm-received' Q 'digits/at' IMp
pacific = America/Los_Angeles|'vm-received' Q 'digits/at' IMp

[default]
200 => 739182,Alice Smith,alice@example.com,,tz=eastern
201 => 825406,Bob Jones,bob@example.com,,tz=central

[sales]
300 => 731905,Sales Team,sales@example.com,,tz=eastern

This baseline records one WAV file per message, enforces six-digit PINs, attaches messages to email, and disables silence detection. Replace all example addresses and PINs before deployment.

Mailbox definition syntax

Each mailbox belongs to the contextA named section of the dialplan that groups extensions. Calls enter a specific context and can only reach extensions visible from it, making contexts the basic unit of call routing and security. named by its section:

[context-name]
mailbox => password,name,email,pager,options

Other Asterisk components must reference an app_voicemail mailbox as mailbox@context, such as 200@default or 300@sales.

The fields are:

Common mailbox options include tz, attach, attachfmt, delete, and maxmsg. Settings defined globally can generally be overridden per mailbox unless upstream documentation marks an option otherwise.

[default]
200 => 739182,Alice Smith,alice@example.com,,tz=eastern|attach=yes|attachfmt=wav

Prefixing the password with - makes it unchangeable:

200 => -739182,Alice Smith,alice@example.com,,tz=eastern

Only use an unchangeable PIN when another system owns the credential and users have a secure reset process.

Core general settings

Defaults and supported options can change between Asterisk versions. Check the sample file shipped with the exact installed release as well as the current upstream sample.

Recording formats and existing messages

[general]
format = wav

Multiple values such as wav49|gsm|wav normally store every message in every listed format. That can avoid transcoding for some consumers, but it also increases storage.

The first format has special significance for IMAP voicemail storage, where only the first configured format is used. Email attachments normally follow the first format, but a mailbox can select another recorded format with the per-mailbox attachfmt option:

[default]
200 => 739182,Alice Smith,alice@example.com,,attach=yes|attachfmt=wav

Email delivery and retention

Asterisk passes notification messages to mailcmd. Installing a general mail client does not prove that this command exists or works. Confirm the configured executable, then leave an actual voicemail and inspect both the Asterisk log and the mail transport log.

[general]
serveremail = asterisk@example.com
attach = yes
mailcmd = /usr/sbin/sendmail -t

For transport setup, templates, attachment choices, and end-to-end testing, see Voicemail with Email Notification.

The delete=yes mailbox option removes the server copy after notification:

[default]
200 => 739182,Alice Smith,alice@example.com,,attach=yes|delete=yes

Password policy and storage

Use minpassword for a basic length requirement:

[general]
minpassword = 6

For stronger rules, externpasscheck calls an external validator with the mailbox, context, old PIN, and proposed PIN. The validator prints VALID or INVALID to standard output.

[general]
externpasscheck = /usr/local/bin/voicemailpwcheck.py

By default, app_voicemail reads and writes PINs in voicemail.conf. This setting stores changed PINs in a separate secret.conf file inside each mailbox directory:

[general]
passwordlocation = spooldir

The spool file contains the PIN in plain text. Restrict access to both /etc/asterisk and the voicemail spool, and include the active password location in backup and restore procedures.

Use externpass when an external system completely owns password changes. Use externpassnotify when Asterisk should still change its local password and notify another system so it can stay synchronized. Review the arguments and failure behavior in the sample configuration before enabling either hook.

Timezone message formats

[zonemessages] entries pair a timezone name with a spoken date and time format:

[zonemessages]
eastern = America/New_York|'vm-received' Q 'digits/at' IMp
central24 = America/Chicago|'vm-received' q 'digits/at' H N 'hours'

Assign a zone with the per-mailbox tz option. Use a timezone present in the operating system's zoneinfo database, and verify the installed Asterisk sound prompts support the selected format.

[default]
200 => 739182,Alice Smith,alice@example.com,,tz=eastern

External notifications

externnotify runs a program when voicemail state changes. The script receives the context, extensionA dialplan entry that matches a dialed number or pattern within a context and triggers a sequence of prioritized steps., and number of new messages.

[general]
externnotify = /usr/local/bin/voicemail-notify

Treat notification scripts as production integrations. Use an absolute path, validate inputs, apply execution timeouts outside Asterisk where appropriate, restrict permissions, and log failures without exposing mailbox PINs or message contents.

Storage backends

Filesystem storage

The default app_voicemail backend stores messages and greetings below the Asterisk spool directory, commonly /var/spool/asterisk/voicemail/<context>/<mailbox>/. Back up the configuration, message metadata, recordings, greetings, and any secret.conf files together.

ODBC storage

ODBC voicemail is not enabled by setting odbcstorage alone. A working deployment requires the voicemail ODBC storage module, a database schema compatible with the installed Asterisk version, a functioning connection in res_odbc.conf, and matching storage and table settings in voicemail.conf.

Current upstream examples commonly use a connection and schema named voicemail, but the configured odbcstorage value must match the resource name in your own res_odbc.conf. The table name must match the deployed schema. Test new message storage, playback, deletion, MWI, backup, and restore before migrating active mailboxes.

IMAP storage

IMAP voicemail requires Asterisk to be built with IMAP support and needs server, authentication, folder, and polling decisions. Only the first recording format is used with IMAP storage. Treat conversion from filesystem or ODBC storage as a migration project with backups and rollback, not as a single configuration toggle.

The upstream voicemail.conf.sample documents the version-specific ODBC and IMAP options. A dedicated deployment guide is appropriate only when it includes a complete, tested schema, module, migration, backup, and rollback workflow.

Reload and verify

Reload app_voicemail after editing the file:

asterisk -rx "voicemail reload"

Confirm that Asterisk loaded the users and timezone definitions:

asterisk -rx "voicemail show users"
asterisk -rx "voicemail show zones"

Then place test calls that cover message recording, short-message rejection, mailbox login, greeting playback, MWI, email delivery, and any configured external or remote storage.

Related content

• Setting Up Voicemail in Asterisk
• Voicemail with Email Notification
• Voicemail maxsilence Must Be Less Than minsecs
• VoiceMail() application reference
• VoiceMailMain() application reference

Primary sources

• Current Asterisk voicemail.conf sample
• Current app_voicemail source
• Official Asterisk voicemail overview