Email Delivery

The Email Delivery screen controls how email leaves the platform: the address messages are sent from, and whether this server delivers them itself or hands them to a mail provider you already use.

The platform sends mail for several features. Voicemail notifications, scheduled reports, welcome messages for new users, password resets and invite links all go out the same way, so this one screen decides the fate of all of them.

Why this matters

A mail server that receives a message decides whether to accept it, file it as spam, or discard it. That decision is based mostly on whether the sending server looks like it is allowed to send for the address in the message.

Left alone, a newly installed PBX is in the worst position for that test: a server address with no sending history, often a generic reverse DNS name from the hosting provider, and a sending domain that has never published a record saying this server may send on its behalf. The visible result is that some recipients get voicemail notifications and others do not, with nothing in the log to explain the difference, because a message treated as spam is usually discarded silently rather than rejected with an error.

Sending through a mail provider you already have solves this in one step. The provider’s servers have the reputation, the DNS records and the signing keys, and your messages arrive with their standing rather than your server’s.

How mail leaves the platform

Everything the platform sends is handed to the mail server running on the same machine, which is what actually delivers it. This screen configures that local mail server. There are two ways it can work.

Direct delivery means the local mail server looks up each recipient’s mail server and contacts it itself. Nothing else is involved. This works when the server has a permanent address with a reverse DNS name that matches your sending domain, outgoing port 25 is not blocked, and the domain publishes a DNS record listing this server’s address as an authorised sender. Many hosting providers block outgoing port 25 by default to limit spam, which makes direct delivery impossible on those networks regardless of how everything else is configured.

Sending through a mail provider, often called relaying or using a smart host, means the local mail server hands every message to one mail server run by someone else, usually with a user name and password, and that server delivers it onward. Microsoft 365, Google Workspace, Amazon SES, SendGrid, Mailgun and most hosting companies all offer this. The connection is normally made on port 587 and is encrypted.

Setting the sender address

From address is the address recipients see, and it is what a receiving mail server checks against the sending domain. Leave it empty and the platform builds one from the service address, in the form noreply@pbx.example.com.

Choose an address on a domain you control and can publish DNS records for. If you send through a provider, the domain will usually need to be one the provider knows about - most require the sending domain to be verified in their console before they will accept mail claiming to come from it.

Sender name is the name shown in front of that address, so a recipient sees Acme Communications <noreply@pbx.example.com> rather than the address on its own. It applies to Manager email and to voicemail notifications alike. Leaving it empty is worth avoiding: voicemail notifications then arrive under a generic built-in name that is not your company’s.

Below the fields, Sending domain reports whether the domain’s DNS currently permits this platform to send using that address. The check runs each time the screen is saved, and its result is shown with the time it ran.

What the sending domain check looks at

A domain can publish a DNS record called SPF (Sender Policy Framework) that lists which servers are allowed to send mail for it. Receiving mail servers read that list and compare it with the server that actually delivered the message. If the domain publishes such a record and the sending server is not on the list, strict receivers reject the message outright.

What the check reports depends on how you deliver:

Sending through a provider: the check looks for the provider’s own entry in your SPF record, usually an include: for the provider’s domain. Your provider’s documentation gives the exact value to publish.
Direct delivery: the check looks for this server’s public address. On a redundant pair it looks for both servers’ addresses, because after a failover the mail comes from the other machine. A record that lists only the active server is reported, so you find out before the failover rather than after it.

Three outcomes are possible. Authorised means the record lists this platform. Not listed means the domain publishes a record that does not include it, which is the case strict receivers reject, and the message on screen gives the record to publish. No record means the domain publishes nothing, which most receivers tolerate but some treat with suspicion.

The check reports; it does not block. A DNS record belongs to whoever runs the domain, which is often not the person configuring the PBX, so the setting is saved either way and the work item is handed to you in plain terms.

Setting up a mail provider

Set Delivery method to Send through a mail provider.

A provider’s server name, port and encryption are published settings that are the same for every account, so the platform knows them for the services most often used here and can fill them in. That matters because those three fields fail unhelpfully when they are wrong: a wrong port produces a connection that hangs rather than an error that says what is missing. Credentials are never filled in, because those belong to your account rather than to the provider, and every field stays editable afterwards, so a provider that gave you settings differing from its published ones can still be entered by hand.

Provider - pick the service you send through, or Other if it is not listed. Picking one fills in the next three fields.
Server name - the provider’s mail server, for example smtp.example.com.
Port - 587 for STARTTLS, which is what nearly every provider uses. Use 465 for TLS from the start. Port 25 is normally blocked for outgoing mail and should not be used here.
Encryption - the options are explained below. STARTTLS if offered is a safe default for a provider on the internet; STARTTLS required is better once you know the provider supports it.
Authentication - leave as User name and password unless the provider accepts mail from your server address without credentials.
User name and Password - as issued by the provider. The user name is often a full email address, and it does not have to match the From address.
Click Test Connection before saving.

The provider shown when you reopen the screen is worked out from the server name, not stored separately, so a server name edited by hand cannot leave the screen naming a provider it no longer points at.

What each provider still needs from you

Each of these is a credential requirement the provider imposes, and each is a common first failure. The settings filled in alongside them are listed so you can recognise them.

Gmail (smtp.gmail.com, port 587, STARTTLS) - Google does not accept the password used to sign in to the account. Create an app password for this server and use that instead.
Google Workspace SMTP relay (smtp-relay.gmail.com, port 587, STARTTLS) - the relay has to be turned on for your domain in the Workspace admin console, where you either list the public address of this server or require SMTP authentication. Because of that choice, this is the one provider where Authentication is left as you had it rather than set for you.
Microsoft 365 (smtp.office365.com, port 587, STARTTLS) - authenticated SMTP has to be enabled for the mailbox you are using. It is switched off by default for many organisations, and disabled entirely while security defaults are on.
SendGrid (smtp.sendgrid.net, port 587, STARTTLS) - the user name is the word apikey, exactly that rather than an email address, and is filled in for you. The password is the API key you generate.
Mailgun (smtp.mailgun.org, port 587, STARTTLS) - credentials belong to a sending domain rather than to the account as a whole, so use the ones shown for the domain you send from.

A service whose server name varies by account or region, such as Amazon SES, is not in the list because there is no single value to fill in. Choose Other and enter the endpoint the service gives you.

Choosing the encryption setting

STARTTLS if offered connects in the clear and upgrades to an encrypted connection if the provider offers one. If the provider does not, the message is still delivered unencrypted. This never causes a delivery failure, which is why it is the default, but it also means a network problem could silently downgrade the connection.
STARTTLS required does the same upgrade but refuses to send if it cannot be established. Use this with any provider on the public internet.
TLS from the start (port 465) encrypts the connection from the first byte instead of upgrading an existing one. Some providers offer only this.
None sends everything, including the password, in a form anyone between this server and the provider can read. Use it only on a private network with a mail server you run.

Verify certificate appears with the two settings that require encryption. Turned on, the platform checks that the provider presents a certificate issued for the name you entered and signed by a recognised authority, which is what stops another machine from impersonating the provider. Turn it off only for a provider using a self-signed certificate.

The field is deliberately absent for STARTTLS if offered. In that mode a certificate problem cannot cause the message to be held back without also defeating the point of the setting, so the platform does not offer a check it would not act on.

Advanced settings

These are for specific providers and can normally be left alone.

Rewrite sender address changes the address the platform gives at the mail server level, as opposed to the one in the message, to the From address above. Some providers accept mail only when that lower-level address matches the account. Leave it off unless the provider rejects mail without it. It can also make replies to bounced messages go somewhere unexpected.
Announce as sets the name this server gives when it introduces itself to the provider. Empty means the server’s own host name. Set it when the provider expects a particular name.
Backup server name and Backup port give a second mail server that is tried only when the first cannot be reached. Leave them empty unless your provider offers one.

Testing

The screen has two tests and they prove different things. Use both.

Test Connection opens the connection to the provider exactly as the mail server will, authenticates, and stops before sending anything. It works on what is currently on screen, so you can try a setting without committing it. This is the only practical way to catch a wrong password: a rejected login does not produce an error anyone sees, it produces mail that sits in the queue being retried for days.

Send Test Email sends a real message the same way every system message is sent, so it exercises the whole path including the receiving side. Send it to an address on a different provider than the one you are configuring. If it does not arrive, check the spam folder first, then open Diagnostics > System Logs > Mail delivery, which is the server’s own record of the conversation with the provider and gives the reason for any rejection in the provider’s own words. It is the file /var/log/maillog if you would rather read it on the server.

Sending a tenant’s voicemail as that tenant

Everything above is system-wide: one sender name and one address for the whole platform. On a system serving several organisations that is often the wrong impression to give, because a voicemail notification arriving from the provider’s own name tells the recipient nothing about the service they actually bought.

A tenant can therefore be given its own sender for voicemail notifications, on Organization > Branding > Email:

Voicemail sender name - the name in front of the address, such as Acme Voicemail.
Voicemail sender address - the address the notifications come from, such as voicemail@acme.example.

Each is optional and each falls back on its own, so setting only the name keeps the system-wide address. Leaving both empty means the tenant follows the system settings entirely, which is how every tenant behaves until someone changes it.

Only a system administrator can see or set these. They are deliberately not available to a tenant’s own administrators: the address a tenant sends as determines whether its mail is accepted, and correcting a bad choice means editing DNS the tenant may not control. The intended workflow is that the system administrator agrees the address with the customer and sets it on their behalf.

This covers voicemail notifications only. Welcome messages, password resets, invite links and scheduled reports are sent by the Manager and use the system-wide sender regardless of which tenant they concern.

Each tenant domain needs its own DNS record

This is the part that is easy to underestimate. Giving a tenant its own address moves the delivery decision onto a domain that tenant owns, so that domain now needs its own SPF record authorising this platform, exactly as the system-wide sending domain does. One correct system-wide record does not cover it.

The same check therefore runs when you save a tenant’s address, and reports what needs publishing if the domain does not authorise the platform. As with the system-wide check it reports rather than blocks, because the record belongs to the customer.

The practical consequence: a tenant address on a domain with no suitable record is more likely to be rejected than the system-wide address it replaced. Set it only where the customer can publish the record, and confirm delivery afterwards by leaving a test voicemail.

Redundant systems

On a high availability cluster or an active and standby pair, everything on this screen reaches both servers, by two different routes. The delivery settings - the provider, its server name, port, encryption and credentials - are held in the platform database, which is replicated. The sender address and sender name are held in the server’s own configuration file instead, and that file is copied from the active server to the standby during the standby’s hourly maintenance pass and again when it is promoted.

One consequence of that direction of travel: the active server is the source of truth for the sender. Editing it on the standby has no lasting effect, because the next pass copies the active server’s version over it. Make the change on the active server.

The mail server’s own configuration files are not replicated; they are local to each machine. Each server therefore compares its own mail configuration against the saved settings during the same hourly pass and rewrites it if the two differ, which is also what applies the replicated settings on a standby. The voicemail sender Asterisk uses is corrected on that pass too, so a system upgraded from a version that had no Email Delivery screen is repaired without anyone opening it.

The readiness screen reports a difference between the two as a warning rather than a blocking problem, so you can see the state of a server before you rely on it.

One thing to check for the pair as a whole: with direct delivery, mail comes from whichever server is active, so both servers’ public addresses need to be authorised by the sending domain. The sending domain check does look at both and reports when only one is listed. With a mail provider this does not arise, because both servers hand mail to the same provider.

Where the settings are stored

The relay password is encrypted in the platform database and is never sent back to the browser. The password field on the screen is always blank when it loads, and leaving it blank keeps the password already saved, so you can change the server name or the port without retyping a password you may not have. The credentials the mail server reads are written to a file readable only by the system account.

Switching from a provider back to direct delivery removes the relay settings from the mail server’s configuration but keeps them on this screen, so switching back does not mean entering them again.

Best practices

Send through a provider you already use rather than configuring direct delivery, unless you have a permanent server address with matching reverse DNS and control over the domain’s DNS records.
Use a From address on a domain you control, and publish the DNS record the sending domain check asks for. An address on a domain belonging to someone else will be rejected by strict receivers no matter how the relay is set up.
Require encryption once you have confirmed the provider supports it. STARTTLS if offered is the right setting to start with and the wrong one to stay on.
Run both tests after any change, and send the test message to a different provider than the one you are configuring.
Check the sending domain result after saving. It is the difference between mail that is delivered and mail that is accepted and filed as spam.
On a redundant pair, test from both servers rather than only from the active one.
Give a tenant its own voicemail sender only when that tenant can publish the DNS record for its domain. Without it the notifications are more likely to be rejected than the system-wide address they replaced.

Preferences - the service address, which the default From address is built from
Email Templates - the content of welcome, password reset and invite messages
Standby Server - replication and promotion on an active and standby pair
HA Cluster - a mirrored two node cluster