Appwrite v0.7 and above come with support for easy integrations with 3rd party SMTP providers. In order for emails to work, you will need to set up proper SMTP configuration as described below.
Because email deliverability can be both tricky and hard, it is often easier to delegate this responsibility to a 3rd-party SMTP provider. These providers help you abstract the complexity of passing SPAM filters by doing a lot of the advanced configuration and validation for you.
In this document, you will learn how to connect a 3rd party SMTP provider like MailGun or SendGrid with Appwrite to help you get better email deliverability.
Setting up Appwrite Messaging?
This page describes how to setup messaging for your self-hosted Appwrite instance to send email verifications and magic URLs during login.
If you are looking to send custom emails for promotions, news letters, and other purposes, view the documentation for Appwrite Messaging documentation.
Environment variables
At this stage, we assume that you have already installed Appwrite. If not, you can follow our Self Hosting Guide for the installation. Appwrite offers multiple environment variables to customize your server setup to your needs. To configure Appwrite to use your own SMTP server, you need to set the following environment variables in the hidden .env file that comes with your Appwrite installation.
| Environment Variable | Description | Default Value |
| _APP_SMTP_HOST | SMTP server host name address. Use an empty string to disable all mail sending from the server. | Empty string |
| _APP_SMTP_PORT | SMTP server TCP port. | Empty |
| _APP_SMTP_SECURE | SMTP secure connection protocol. Change to 'tls' if running on a secure connection. Valid values: empty, 'tls', 'ssl'. | Empty |
| _APP_SMTP_USERNAME | SMTP server user name. | Empty |
| _APP_SMTP_PASSWORD | SMTP server user password. | Empty |
| _APP_SYSTEM_EMAIL_ADDRESS | Configured sender email address, seen by recipients. | "team@appwrite.io" |
Here's a sample configuration if you're using SendGrid as your SMTP provider:
_APP_SMTP_HOST=smtp.sendgrid.net
_APP_SMTP_PORT=587
_APP_SMTP_SECURE=tls
_APP_SMTP_USERNAME=YOUR-SMTP-USERNAME
_APP_SMTP_PASSWORD=YOUR-SMTP-PASSWORD
_APP_SYSTEM_EMAIL_ADDRESS=YOUR-SENDER-EMAIL
Applying changes
After editing your docker-compose.yml or .env files, you will need to recreate your Appwrite stack by running the following compose command in your terminal.
docker compose up -d
You can verify if the changes have been successfully applied by running this command:
docker compose exec appwrite vars
Debugging
If you are unable to send emails, there is most likely an issue with your integration. The first place to look for possible errors is the Appwrite Emails Worker. You can access the logs of this container using:
docker compose logs -f appwrite-worker-mails
The next possible source of error is the configuration in your .env file. Make sure that the keys and values are correct and test the credentials by sending a test email using your SMTP provider's SDK or cURL requests.
Moving on to the next source of error. Some SMTP providers have a concept of authorized recipients in their sandbox (or dev) environments and you can only send emails to recipients in this list. Make sure that the recipient of the email that you're trying to send is a part of this list.
Another source of error could be that the environment variables have not been set in the appwrite container. You can check this using:
docker compose exec appwrite-worker-mails vars
If this is the case, you can try rebuilding your appwrite stack using:
docker compose up -d --build --force-recreate
Now you can head over to your Appwrite Console, log out from your account, and try to recover your password or send invites to other team members from your Appwrite Console using your newly configured SMTP provider.