VMware ESXi and vSphere Cluster Management

Voicemail in Asterisk: Configuration, Mailboxes, Greetings, and Notifications

Learn how to configure Asterisk voicemail, define mailboxes, route calls with the dialplan, manage greetings, enable email and MWI, and troubleshoot delivery.

Asterisk is an open-source PBX and communications platform. Its built-in voicemail service accepts and stores recorded messages when a subscriber does not answer, is busy, or cannot be reached. The service has traditionally been associated with the name Comedian Mail.

Voicemail is useful in businesses for individual employees, departments, after-hours service, and on-call teams. In residential systems, it provides a private message box for each household member. Asterisk voicemail combines password-protected mailboxes, telephone-based message management, greetings, email notifications, audio attachments, and Message Waiting Indicator (MWI) support.

How Asterisk voicemail works

A voicemail mailbox is a password-protected destination for messages. A mailbox is identified by a number and a mailbox context, such as 1000@default. The number identifies the mailbox inside the context; the context is a logical namespace that prevents similarly numbered mailboxes from being confused.

Voicemail configuration alone does not send callers to voicemail. The dialplan must invoke VoiceMail() when a call is unanswered, busy, or otherwise unavailable. Subscribers use VoiceMailMain() to log in, listen to messages, record greetings, and manage their mailbox.

Feature	What it does	Typical user or administrator benefit	Related configuration area
Password-protected mailbox	Requires a PIN for subscriber access	Prevents unauthorized message retrieval	`voicemail.conf` and `VoiceMailMain()`
Message recording	Stores a caller's recorded message	Preserves calls that cannot be answered	`VoiceMail()` and voicemail storage
Greetings	Plays default or personal unavailable, busy, and temporary prompts	Explains what the caller should do	Mailbox settings and subscriber menu
Email notification	Sends an alert when a message arrives	Allows remote awareness of new messages	Mailbox email fields and `[general]`
Audio attachment	Includes a copy of the recording in email	Allows playback without calling the PBX	Global attachment behavior and mail transport
MWI	Publishes waiting-message state	Lights a phone lamp or supplies stutter dial tone	Endpoint subscription and mailbox identity
Forwarding	Sends an existing message to another mailbox	Lets users share or delegate messages	Subscriber voicemail interface
Group voicemail	Delivers one recording to several mailboxes	Supports team announcements and on-call notices	Recipient grouping and dialplan or installed feature

Configuring voicemail.conf

The primary voicemail configuration file is /etc/asterisk/voicemail.conf. It normally contains system-wide settings, mailbox contexts, mailbox entries, email templates, and optional advanced behavior. The exact available options can vary by Asterisk version, so confirm names and defaults with the documentation installed for your system.

touch /etc/asterisk/voicemail.conf

Do not overwrite an existing file merely to create it. First inspect the current configuration and preserve any distribution-specific settings.

Section	Purpose	Typical contents	Example use
`[general]`	Defines system-wide voicemail behavior	Server sender address, attachment behavior, defaults, and other global options	Set the sender address used for notifications
`[default]`	Provides a common mailbox namespace	Mailbox entries	Store employee mailboxes such as `1000`
`[sales]`	Provides a separate logical namespace	Department mailbox entries	Identify a shared mailbox as `1000@sales`
`[engineering]`	Provides another namespace	Engineering mailbox entries	Use the same number independently from another context
Template-related sections	Customize notification subjects and message bodies when supported	Email templates and substitutions	Brand or localize notification text

Context names matter because dialplan applications refer to the complete mailbox identity. A call to VoiceMail(1000@default,u) is not necessarily directed to the same mailbox as VoiceMail(1000@sales,u).

Mailbox entry syntax

The basic mailbox format is:

mailbox_number => password,subscriber_name,email_address,pager_address,options

[default]
1000 => 7391,Alice Example,alice@example.com

Field order	Field name	Required or optional	Meaning	Example value
1	Mailbox number	Required	Unique mailbox identifier within its context	`1000`
2	Password or PIN	Required in normal use	Initial subscriber authentication value; the user may change it when permitted	`7391`
3	Subscriber name	Optional but recommended	Display or spoken identification associated with the mailbox	`Alice Example`
4	Email address	Optional	Recipient of voicemail notifications	`alice@example.com`
5	Pager address	Optional	Legacy or separate notification destination where supported	`pager@example.com`
6	Options	Optional	Additional mailbox-specific behavior, depending on the installed version	Version-specific

Use unique mailbox numbers within each context and nontrivial initial PINs. A short sequential PIN is easy to guess. Configure password policy and require subscribers to replace administrative or initial PINs.

Email settings

A mailbox email address enables notifications, but the host must also be able to deliver outbound mail through a functioning local mail transfer agent or configured relay. Global settings commonly control the sender address, subject and body templates, and whether the recorded audio is attached.

[general]
serveremail=pbx@example.com
attach=yes

Notification-only email tells the recipient that a message exists. Attachment-enabled email includes a copy of the recording. Sending recordings by email creates privacy and retention risks: messages may be copied to multiple devices, stored by third-party providers, or forwarded outside organizational control. Disable attachments where policy requires telephone-only retrieval, and protect both mailboxes and email transport.

Dialplan integration

Application	Primary purpose	Typical call flow position	Key inputs
`VoiceMail()`	Plays a greeting and records a caller's message	After busy, no-answer, or unavailable handling	Mailbox number, context, and options
`VoiceMailMain()`	Provides subscriber login and management menus	Dedicated internal access extension or direct feature code	Optional context and caller or prompted credentials

Send unanswered calls to a mailbox

This example rings endpoint 1000 for 20 seconds and then deposits the call into mailbox 1000@default. The u option requests unavailable-greeting behavior. A busy route can use the corresponding busy-greeting behavior; option names and additional choices should be checked against the installed version.

exten => 1000,1,Dial(PJSIP/1000,20)
 same => n,VoiceMail(1000@default,u)
 same => n,Hangup()

Common routing designs include sending a direct extension to voicemail after a timeout, sending busy calls directly to voicemail, using a dedicated voicemail access extension, and offering a direct-to-mailbox or voicemail escape option from an IVR. Options can also allow a caller to skip parts of the greeting or instructions where that behavior is appropriate. Test the exact caller experience after choosing options.

Provide subscriber access

exten => *97,1,VoiceMailMain(@default)
 same => n,Hangup()

From the phone, a subscriber selects the access extension, enters a mailbox number when prompted, and authenticates with the mailbox password. A deployment with several contexts may provide separate access routes or otherwise ensure that the correct context is selected. Menu prompts and key behavior vary with Asterisk version, language, and configuration.

Typical subscriber tasks include listening to new or saved messages, replaying, saving, deleting, forwarding to another mailbox, changing folders, recording or replacing greetings, changing the PIN, and exiting. Users should be shown the actual menu sequence used by their system rather than relying on a key map from another version.

Greetings and the caller recording flow

Greeting type	When played	Who records it	Fallback behavior
Unavailable	The subscriber cannot answer or is unreachable	Subscriber or administrator	Asterisk uses the default unavailable prompt if no personal greeting exists
Busy	The subscriber is busy	Subscriber or administrator	Asterisk uses the default busy prompt if no personal greeting exists
Temporary	A temporary condition, such as vacation or closure, should be announced	Subscriber	Normal greeting behavior resumes when the temporary greeting is removed
Name recording	Used by menus or prompts that identify the subscriber	Subscriber	A system or mailbox default may be used if no name is recorded

The dialplan invokes VoiceMail() for the target mailbox.
Asterisk selects the busy, unavailable, temporary, or fallback greeting.
The caller hears instructions and records a message.
The caller may review or confirm the recording, depending on configuration.
Asterisk stores the message, updates mailbox state, and may send notification email.

Subscribers normally record or replace greetings through the VoiceMailMain() menus. A temporary greeting is useful because it can override the normal greeting without permanently replacing it.

Message Waiting Indicator

MWI means Message Waiting Indicator. Asterisk publishes mailbox state when new or urgent messages exist. Compatible phones may show a visual message lamp, and some systems provide a stutter dial tone, an interrupted dial tone that signals waiting voicemail.

Endpoint configuration must subscribe to or monitor the correct mailbox identifier. The mailbox used by VoiceMail(), the mailbox monitored by the endpoint, and the context portion of that identity must agree. For example, monitoring 1000@sales will not necessarily show messages deposited into 1000@default.

One endpoint or user can be associated with more than one mailbox. This is useful when an assistant monitors an executive mailbox or several staff members monitor a shared departmental inbox. MWI associations determine which states appear on the phone; they do not change the mailbox target selected by dialplan routing.

Forwarding, shared mailboxes, and group voicemail

Forwarding an existing message

Voicemail forwarding sends a recorded message from one mailbox to another through the subscriber interface. A user can listen to a message and select the forwarding function, then identify one or more permitted destination mailboxes. Forwarding should be controlled when messages contain confidential information.

Shared departmental mailbox

A shared sales mailbox is a single mailbox that several staff members access or monitor. Calls can be routed to it after a sales queue or extension group goes unanswered. This is different from giving every salesperson an individual mailbox: the message is stored in one shared destination, while several endpoints may monitor its MWI state or authorized users may log in to retrieve it.

Group voicemail or broadcast

Group voicemail delivers one recorded message to multiple subscriber mailboxes. It is appropriate for service announcements, on-call teams, emergency notices, or departmental messages. Recipient groups must be explicit and narrowly scoped; an overly broad group can disclose sensitive information or create unnecessary notifications.

Group voicemail is not the same as a shared mailbox. A shared mailbox stores one message in one common destination. Group voicemail creates delivery to multiple individual destinations. The exact implementation depends on the Asterisk version and installed dialplan or feature set, so test duplicate delivery, permissions, retries, and MWI behavior before production use.

Scalable dialplans with extension patterns

An extension pattern is a reusable dialplan expression that matches a family of dialed numbers. Patterns begin with an underscore. This can avoid writing a separate route for every employee, but a pattern must be constrained so that callers cannot reach nonexistent or unintended mailboxes.

Symbol	Matches	Voicemail routing example	Caution
`_`	Marks the expression as a pattern	`_1XXX` matches four-digit extensions beginning with 1	Without the prefix, Asterisk treats the text as a literal extension
`X`	Any digit from 0 through 9	`_1XXX` can derive a four-digit mailbox	May match numbers that have no mailbox
`Z`	Any digit from 1 through 9	Use where a position must not be zero	Do not assume it matches every digit
`N`	Any digit from 2 through 9	Use where a position must be at least 2	Excludes 0 and 1
`[...]`	One digit from a specified set or range	`_10[0-5]` matches 100 through 105	Define the intended range precisely
`.`	One or more remaining characters	Can match variable-length destinations	Broad matches can capture unintended calls
`!`	Zero or more characters in immediate-match behavior where supported	Special applications may use it for early matching	Can seize calls before a more specific route; use carefully

exten => _1XXX,1,VoiceMail(${EXTEN}@default,u)
 same => n,Hangup()

Here, the dialed extension is used as the mailbox number. In a real system, validate that the matched extension has an endpoint and a corresponding mailbox. Prefer an explicit list, a narrower pattern, or a lookup and fallback route that plays an error message instead of sending callers to an invalid mailbox.

Reloading and operational maintenance

After editing voicemail.conf, reload voicemail configuration. After editing the dialplan, reload the dialplan separately.

asterisk -rx "voicemail reload"
asterisk -rx "dialplan reload"
asterisk -rx "voicemail show users"

The last command is available on versions that provide that CLI operation. Use the Asterisk CLI help system and version-specific documentation when a command is unavailable.

Voicemail recordings and metadata are stored under the Asterisk voicemail storage area, commonly within the Asterisk spool hierarchy. Avoid manually renaming, deleting, or editing message files and metadata while Asterisk is using them. Uncoordinated changes can make messages disappear from menus or leave inconsistent state.

Monitor free disk capacity and alert before recording storage is exhausted.
Back up recordings and configuration according to business requirements.
Define retention and deletion rules for old messages.
Keep storage ownership and permissions compatible with the Asterisk service account.
Check mail transport permissions and logs when notifications fail.
Test restore procedures, not only backup creation.

Security and privacy

Use nontrivial mailbox PINs and require users to change initial credentials.
Limit direct external access to VoiceMailMain(), or protect it with additional authentication and access controls.
Do not enable audio attachments when organizational or regulatory policy prohibits sending recordings through email.
Protect voicemail directories, backups, administrative files, and mail transport credentials.
Use retention limits because voicemail recordings may contain personal, financial, or confidential business information.
Avoid placing unnecessary personal or organizational details in greetings and spoken mailbox names.
Restrict group voicemail recipient lists and forwarding permissions where supported.

Troubleshooting checklist

Symptom	Likely cause	Verification step	Corrective action
Calls ring indefinitely or disconnect	No voicemail priority, incorrect timeout, or wrong target	Trace the executed dialplan and inspect the `Dial()` result	Add busy or no-answer handling and verify the mailbox context
Invalid mailbox message	Mailbox does not exist, context is mistyped, or pattern matched an unprovisioned extension	Compare `VoiceMail()` with the entry in `voicemail.conf`	Correct the identity or add validation and a fallback route
MWI lamp stays off	Unsupported or disabled subscription, wrong mailbox identity, or no new message	Check endpoint MWI configuration and mailbox state	Monitor the correct number and context and verify message state
No email arrives	Missing address, disabled notification, broken mail transport, spam filtering, or rejected sender	Inspect mailbox fields, global settings, and mail logs	Fix recipient and sender settings and restore outbound delivery
Email has no recording	Attachments disabled, configuration not reloaded, or version-specific behavior	Review attachment settings and create a fresh test message	Enable the intended behavior, reload, and retest
Subscriber cannot log in	Wrong mailbox, context, PIN, or access route	Confirm `VoiceMailMain()` context and credentials	Correct the route or perform a controlled PIN reset
Recordings fail or disappear	Low disk space, bad permissions, cleanup, filesystem, or backup failure	Check capacity, ownership, logs, retention jobs, and storage health	Repair capacity or permissions and review retention and backup procedures

End-to-end configuration checklist

Create or review /etc/asterisk/voicemail.conf.
Set global behavior in [general], including email and attachment policy if required.
Create the required mailbox contexts.
Define unique mailbox numbers, secure initial PINs, subscriber names, and email addresses.
Reload voicemail configuration.
Add VoiceMail() to busy and no-answer call paths.
Add an internal VoiceMailMain() access extension.
Configure endpoint MWI monitoring with the exact mailbox number and context.
Reload the dialplan.
Test greeting selection, message recording, login, playback, deletion, forwarding, MWI, and email.
Confirm disk monitoring, permissions, backups, and retention policy.

For a compact reference to this lesson, see Voicemail in Asterisk.