Docs

Email Delivery

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 setup 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.

Update Your .env File

At this stage, we assume that you have already installed Appwrite. Else, 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.

_APP_SMTP_HOST - SMTP server host name address. Use an empty string to disable all mail sending from the server. The default value for this variable is an empty string

_APP_SMTP_PORT - SMTP server TCP port. Empty by default.

_APP_SMTP_SECURE - SMTP secure connection protocol. Empty by default, change to 'tls' if running on a secure connection. Valid values are empty, 'tls', and 'ssl'.

_APP_SMTP_USERNAME - SMTP server user name. Empty by default.

_APP_SMTP_PASSWORD - SMTP server user password. Empty by default.

_APP_SYSTEM_EMAIL_ADDRESS - Configured sender email address, "team@appwrite.io" by default. This is the email address seen by recipients.

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

Restart Your Appwrite Server

Once you've updated your .env file, you need to restart your Appwrite instance. Navigate to the directory containing the docker-compose.yml file of your Appwrite instance and run the following command from your terminal:

docker compose up -d

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 providers' 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, logout 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.