Configure Asterisk Voicemail with voicemail.conf

Learn how to configure Asterisk voicemail.conf, including global options, time zones, mailbox credentials, email notifications, dialplan integration, and CLI verification.

voicemail.conf is Asterisk's primary configuration file for voicemail behavior, timestamp announcements, and mailbox definitions. It controls how messages are recorded, how long they may be, how silence is handled, and whether notification email includes an audio attachment.

A mailbox definition alone does not send calls to voicemail. The dialplan must also invoke the VoiceMail application for callers and provide a path to VoiceMailMain for mailbox owners. Review dialplan fundamentals, contexts, and priorities if these concepts are new.

Purpose and location of voicemail.conf

On a typical source or package installation, the file is located at /etc/asterisk/voicemail.conf. The exact configuration directory can vary, so confirm the active Asterisk installation before editing. File ownership and permissions should allow Asterisk to read the file without making voicemail credentials unnecessarily visible to other users. Related service-account administration is covered in adding a system user for Asterisk and changing file ownership.

The file commonly controls:

Preferred audio recording formats.
Maximum message duration and silence behavior.
The sender address and attachment behavior for voicemail notifications.
Named time zones and the prompts used to announce message dates and times.
Mailbox numbers, PINs, owner names, email addresses, and optional mailbox settings.

Configuration file structure

Asterisk configuration files use an INI-style structure. A section name appears in square brackets, and settings usually use name=value. Mailbox entries use a mailbox identifier followed by an arrow and comma-separated fields.

Section	Purpose	Typical contents
`[general]`	Global voicemail behavior	Recording formats, sender address, attachment policy, silence and duration limits
`[zonemessages]`	Named timestamp time-zone definitions	A label mapped to an IANA time zone and announcement format
`[default]` or another mailbox context	Groups mailbox definitions	Mailbox number, PIN, name, email, and optional fields

Settings in [general] apply broadly, while entries in a mailbox context describe individual voicemail accounts. Use comments and consistent whitespace to keep production files maintainable. A semicolon commonly starts a comment; verify the syntax supported by the Asterisk release in use.

General voicemail options

Option	Example value	Effect	Operational considerations
`format`	`wav49\|wav`	Specifies preferred recording formats, in pipe-separated order	Required format modules and release behavior determine what is available; storage and recipient compatibility matter
`serveremail`	`voice@example.invalid`	Sets the sender address used for notification messages	It does not configure outbound mail delivery or guarantee that the address is accepted
`attach`	`yes`	Controls whether the voicemail recording is attached to notification email	Attachments increase message size and expose the recording to email systems and recipients
`maxsilence`	`20`	Sets the tolerated silence threshold used during recording	Units and detailed behavior should be checked against the installed Asterisk version; overly short values can end recordings unexpectedly
`maxmessage`	`200`	Sets the maximum permitted voicemail recording duration	Choose a limit appropriate for callers, storage, and email attachment policies

The format option contains a priority list separated by pipes. wav49 is a legacy Asterisk voicemail format commonly associated with GSM-compressed audio in a WAV-compatible container. It should not be assumed to be identical to uncompressed PCM WAV, and some recipient applications may handle it poorly. Asterisk releases, installed format modules, and package builds can change the available behavior, so validate formats on the target system.

serveremail identifies who the notification appears to come from. It is not an SMTP server, mail-transfer agent, relay, or authentication configuration. The Asterisk host still needs a working outbound mail transport.

Time-zone message definitions

The [zonemessages] section maps a short label to a time zone and a prompt-format expression. For example, berlin can identify a definition based on the IANA time zone Europe/Berlin. IANA time zones are region-based identifiers that account for local offset rules and daylight-saving changes.

The format expression combines sound prompt tokens and formatting directives. In a definition such as 'vm-received' Q 'digits/at' R, quoted tokens refer to sound prompts, while directives such as Q and R tell Asterisk how to assemble date and time information. The exact prompt availability and directive behavior depend on the Asterisk version and installed language sound files.

A mailbox can reference a configured zone through applicable mailbox options. When the zone is correctly assigned, voicemail date and time announcements can be rendered in the mailbox owner's local time rather than the server's local time.

Mailbox definition syntax

A mailbox is a voicemail account identified by a number or name and normally protected by a numeric PIN. A common entry has this form:

mailbox => PIN,Display Name,Email Address

Position	Field	Example	Purpose
Mailbox identifier	Left side of `=>`	`444`	Number or name used to target the mailbox
PIN	First comma-separated value	`2587`	Credential used by the owner to authenticate
Display name	Second value	`Antun Peicevic`	Owner information shown or used in voicemail handling
Email address	Third value	`tuna@example.invalid`	Notification recipient when email delivery is configured
Optional additional fields	Later values or mailbox options	Pager, options, time-zone selection	Adds behavior supported by the installed release and configuration model

The section containing the entry is the mailbox context. It groups related mailboxes and becomes part of the mailbox's identity when referenced by the dialplan. The mailbox number alone may not be sufficient if the same number exists in more than one context.

PINs should be unique, nontrivial, and protected like other credentials. Do not use an extension number, repeated digits, or a value that is easy to guess. Restrict access to voicemail.conf because it contains mailbox authentication data.

Complete example configuration walkthrough

The following is an illustrative configuration. The names, addresses, PIN, limits, and prompt expression are examples, not universal defaults. Replace them with values appropriate for the deployment.

[general]
format=wav49|wav
serveremail=voice@geek-university.local
attach=yes
maxsilence=20
maxmessage=200

[zonemessages]
berlin=Europe/Berlin|'vm-received' Q 'digits/at' R

[default]
444 => 2587,Antun Peicevic,tuna@geek-university.com

format=wav49|wav requests the listed recording formats in preference order, subject to installed modules and release behavior.
serveremail supplies the notification sender address.
attach=yes requests that the recording be included with the notification.
maxsilence=20 and maxmessage=200 establish recording-related limits for this configuration.
berlin names a time-zone definition using Europe/Berlin and a timestamp prompt expression. Validate the referenced sound prompts on the target system.
The [default] context creates mailbox 444, with PIN 2587, owner name Antun Peicevic, and the shown email recipient.

The illustrative values cause Asterisk to record in the selected formats, send notifications from the configured sender, request attachments, apply silence and duration limits, and recognize mailbox 444 in the default context. The example credentials and email address must be replaced in a real installation.

Apply and verify changes

Open the Asterisk CLI from a shell connected to the host:

asterisk -rvvv

After saving voicemail.conf, reload the voicemail configuration:

voicemail reload

Then list the users recognized by Asterisk:

voicemail show users

Command	When to use it	Expected result
`voicemail reload`	After changing voicemail.conf	Asterisk rereads voicemail settings and reports parsing problems when applicable
`voicemail show users`	After reloading or when auditing mailbox definitions	Recognized mailbox numbers, contexts, owner information, and status fields where supported by the release

A successful verification should show mailbox 444 under the expected context, with its owner information. If it does not appear, inspect CLI output for syntax errors, confirm that the edited file is in the active configuration directory, and check file permissions.

Relationship to dialplan voicemail applications

voicemail.conf supplies the mailbox accounts; the dialplan decides when a call is deposited into one and how an owner retrieves messages.

VoiceMail(<context>/<mailbox>) lets a caller leave a message.
VoiceMailMain(<context>/<mailbox>) lets an owner access, listen to, and manage messages.

For the example mailbox, the conceptual targets are:

VoiceMail(default/444)
VoiceMailMain(default/444)

The exact application syntax can include additional options and must be placed in valid dialplan priorities. The context and mailbox must match the section and identifier in voicemail.conf. A user needs an extension, IVR option, feature code, or another dialplan path to reach mailbox access. An unanswered or busy extension must explicitly route to VoiceMail; merely defining mailbox 444 does not change call flow.

See VoiceMailMain application concepts and Asterisk extensions when designing the owner-access and no-answer paths.

Email delivery and attachment considerations

There is an important difference between setting a notification sender and delivering mail. serveremail sets an address in the generated message, but the Asterisk host needs a functioning outbound mail-transfer configuration, suitable DNS and network access, and any required relay authentication or policy compliance.

Verify the mailbox's recipient field and the global serveremail value.
Review the host mail-transfer-agent and delivery logs.
Check spam, quarantine, sender-validation, and attachment filtering.
Consider attachment size: longer messages and less-compressed formats consume more storage and bandwidth.
Test playback on the recipient's mail client and device; not every client supports every Asterisk audio format.

Emailing recordings also creates privacy and retention concerns. Establish who may access messages, how long attachments remain in mailboxes and backups, and whether organizational policy permits recordings to leave the telephony system. Disable attachments when notification-only email is preferable.

Troubleshooting common problems

Mailbox is missing from the user listing

Run voicemail reload and inspect the CLI output.
Check the arrow, commas, section header, and other syntax in the mailbox line.
Run voicemail show users and verify both the mailbox number and context.
Confirm that Asterisk is reading the configuration directory and file that you edited.
Check file ownership and permissions without making the file broadly readable.

Callers cannot leave a message

Confirm that the unanswered or busy dialplan branch invokes VoiceMail.
Confirm that its context and mailbox match the configured values.
Check whether the call is reaching a different extension or call-flow branch.
Use Asterisk CLI call logging and dialplan debugging as appropriate.

Notification email does not arrive

Verify the mailbox email field and serveremail.
Inspect the host's outbound mail and mail-transfer-agent logs.
Test delivery to an allowed recipient and check spam or quarantine folders.
Temporarily disable attachments to determine whether attachment filtering is the cause.

Audio attachment cannot be played

Try a format broadly supported by the intended recipients.
Confirm that the relevant Asterisk format modules are installed and loaded; module installation may be required for source builds.
Play the message through voicemail and test the attachment with more than one recipient client.

Announced date or time is incorrect

Check that the zone uses the correct IANA identifier, such as Europe/Berlin.
Confirm that the mailbox uses the intended configured zone where applicable.
Check the host clock, system time zone, and NTP synchronization.
Verify that the language sound files contain the prompts referenced by the timestamp expression.

Post-change test procedure

Edit and save voicemail.conf with restricted permissions.
Enter the Asterisk CLI and run voicemail reload.
Run voicemail show users and verify the mailbox number, context, and owner details.
Place a test call that follows the intended no-answer or busy route.
Leave a message, access it through the VoiceMailMain path, and verify playback and mailbox management.
If email is enabled, verify notification delivery, sender identity, attachment playback, and handling by the recipient's mail security controls.

Exam-relevant notes

voicemail.conf defines mailboxes; the dialplan sends calls to them.
Mailbox identity includes its context and mailbox identifier. A mismatch in either part can prevent message deposit or owner access.
serveremail is a sender setting, not a complete mail-delivery configuration.
format, maxsilence, and maxmessage affect recording behavior, but exact supported behavior depends on the Asterisk release and installed modules.
Use voicemail reload and voicemail show users to apply and verify configuration changes.