Learn How to Run Your Appwrite Backend Server With Any SMTP Provider for Max Email Deliverability

4 min readApr 26, 2020

Appwrite is a self-hosted backend as a service server that provides web, mobile, and native developers with a set of tools and APIs that aims to help them build applications a lot faster and in a more secure way.

By default, Appwrite uses a default built-in SMTP server. The default SMTP server is a great way to get you started with using Appwrite quickly, but if you plan to move your setup to a production environment, you will have extra configuration work to do in order to make sure email providers respect your SMTP server.

Because email deliverability can be both tricky and hard, it is often easier to delegate this responsibility to a 3rd-party SMTP provider. This provider help you abstract the complexity of passing SPAM filters by doing a lot of the advanced configuration and validation for you.

In this tutorial, you will learn how to connect your own SMTP server or a 3rd party SMTP provider like MailGun or SendGrid with Appwrite to help you get better email deliverability.

Step 1: Install your Appwrite Server

In order to connect Appwrite with your own SMTP server, you first need to install the Appwrite server. Appwrite is a self-hosted solution, and you can install it both on your development machine or on any cloud servers provider like AWS, GCP, Azure, or even DigitalOcean or Linode.

The Appwrite server is packaged as a set of Docker containers. To start Appwrite installation, you first need to make sure you have Docker available on your machine. You can learn more about Docker installation at the Docker official site.

Once your Docker setup is ready, you can start the Appwrite server installation by using the following command from your operating system terminal:

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/install/appwrite:rw \
    -e version=latest \
    appwrite/install

The installation process will be followed by several dialogs regarding your system settings. The setup process will create a docker-compose.yml file with the Appwrite stack and start your backend server. Once done, check your server instance is up by accessing the Appwrite console at https://[your-hostname:your-port]/console .

Step 2: Update your docker-compose.yml File

Appwrite offers multiple environment variables to customize your server setup to your needs. To make Appwrite use your own SMTP server instead of the default build-in SMTP server, you need to change the Appwrite container environment variables.

appwrite:
        image: appwrite/appwrite:latest
        restart: unless-stopped
        networks:
            - appwrite
        labels:
            - traefik.http.routers.appwrite.rule=PathPrefix(`/`)
            - traefik.http.routers.appwrite-secure.rule=PathPrefix(`/`)
            - traefik.http.routers.appwrite-secure.tls=true
        volumes:
            - appwrite-uploads:/storage/uploads:rw
            - appwrite-cache:/storage/cache:rw
            - appwrite-config:/storage/config:rw
            - appwrite-certificates:/storage/certificates:rw
        depends_on:
            - mariadb
            - redis
            - smtp
            - clamav
            - influxdb
            - telegraf
        environment:
            - _APP_ENV=production
            - _APP_OPENSSL_KEY_V1=your-secret-key
            - _APP_DOMAIN=localhost
            - _APP_DOMAIN_TARGET=localhost
            - _APP_REDIS_HOST=redis
            - _APP_REDIS_PORT=6379
            - _APP_DB_HOST=mariadb
            - _APP_DB_PORT=3306
            - _APP_DB_SCHEMA=appwrite
            - _APP_DB_USER=user
            - _APP_DB_PASS=password
            - _APP_INFLUXDB_HOST=influxdb
            - _APP_INFLUXDB_PORT=8086
            - _APP_STATSD_HOST=telegraf
            - _APP_STATSD_PORT=8125
            - _APP_SMTP_HOST=smtp.mailgun.org
            - _APP_SMTP_PORT=587
            - _APP_SMTP_SECURE=tls
            - _APP_SMTP_USERNAME=YOUR-SMTP-USERNAME
            - _APP_SMTP_PASSWORD=YOUR-SMTP-PASSWORD

_APP_SMTP_HOST
SMTP server host name address. Default value is: ‘smtp’

_APP_SMTP_PORT
SMTP server TCP port. Default value is: ‘25’

_APP_SMTP_SECURE
SMTP secure connection protocol. Empty by default, change to ‘tls’ if running on a secure connection.

_APP_SMTP_USERNAME
SMTP server user name. Empty by default.

_APP_SMTP_PASSWORD
SMTP server user password. Empty by default.

Step 3: Remove the Default SMTP Container

As mentioned above, the Appwrite default setup includes the Appwrite default SMTP container. Now that you are using your own SMTP server setting, you don’t need it anymore. Just remove the SMTP container from your docker-compose.yml file:

̶s̶m̶t̶p̶:̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶i̶m̶a̶g̶e̶:̶ ̶a̶p̶p̶w̶r̶i̶t̶e̶/̶s̶m̶t̶p̶:̶1̶.̶0̶.̶1̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶r̶e̶s̶t̶a̶r̶t̶:̶ ̶u̶n̶l̶e̶s̶s̶-̶s̶t̶o̶p̶p̶e̶d̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶n̶e̶t̶w̶o̶r̶k̶s̶:̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶-̶ ̶a̶p̶p̶w̶r̶i̶t̶e̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶e̶n̶v̶i̶r̶o̶n̶m̶e̶n̶t̶:̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶-̶ ̶M̶A̶I̶L̶N̶A̶M̶E̶=̶a̶p̶p̶w̶r̶i̶t̶e̶
̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶ ̶-̶ ̶R̶E̶L̶A̶Y̶_̶N̶E̶T̶W̶O̶R̶K̶S̶=̶:̶1̶9̶2̶.̶1̶6̶8̶.̶0̶.̶0̶/̶2̶4̶:̶1̶0̶.̶0̶.̶0̶.̶0̶/̶1̶6̶

Step 4: Restart Your Appwrite Server

After you finished updating and saving your Appwrite docker-compose.yml server you need to restart your Appwrite stack using the following command from your terminal:

docker-compose up -d --remove-orphans

That’s it! Go to your Appwrite console again and try to create a new user. If everything went OK, you should get a welcome email in your new user email inbox. As of version 0.5, Appwrite uses its SMTP server to send welcome emails, password recoveries, and user invites. By using a well-configured SMTP server, you can make sure your users enjoy a maximum rate of email deliverability.

Learn More

Appwrite is an open-source project that is driven by its community. You can learn more about Appwrite features, API, and integration by visiting Appwrite official website or Github repository. You can also follow Appwrite news and announcements on our Twitter or Facebook accounts. You can also chat with us on our Discord server.

About Me

I am Eldad Fux, an Entrepreneur, Software Architect, open-source enthusiastic, and the creator of appwrite.io. You can follow me on my Twitter account: https://twitter.com/eldadfux or connect with me via LinkedIn: https://www.linkedin.com/in/eldadfux/.