Self hosting Unsend
An end-to-end guide on how to self-host Unsend. An opensource sending infrastructure for developers.
Prerequisites
If you have any questions join #self-host on discord.
Step 1: Environment variables
Unsend depends on AWS ses to send emails and SNS to receive email status. Along with that it also depends on Postgres as a database and Redis for queue. Copy the .env.selfhost.example
file to .env
and fill in the values.
AWS credentials
tl;dr: Login to your AWS console and create a new user with programmatic access. Attach the AmazonSNSFullAccess
and AmazonSESFullAccess
policies to the user. Then create a new access key for the user.
Add the following environment variables.
Follow this for detailed steps: Create AWS credentials
Github app credentials for login
Usend uses github authentication for login.
Use this link to create an github app
Callback URL : https://<your-unsend-instance>/api/auth/callback/github
Add the following environment variables.
Database & Redis
Unsend uses Postgres as a database and Redis as a queue. You need to create a new database and add the following environment variables.
If you’re using docker-compose or our railway template, it’s all automatically done for you.
Next auth url and secret
Url is the app url you’re going to use and secret is random string. You can generate a random secret using this command.
Add the following environment variables.
Step 2: Setting up the app
You can use any platforms that supports docker. You can also use the railway template. In this example I’ll be using railway. If you have any questions drop in the discord channel and i’ll try to help you out
Docker
Follow this guide to setup your docker instance: Set up docker
Railway
This option is very easy. Click on the below button and click “Deploy now”. Add a custom domain etc.
Updating image is easy, click on the 3 dots and redeploy. This will pull the latest image.
Your unsend instance is now live now.
Step 3: Setting up a region
In order to send emails, you need to select an region in aws. Use a region where your users are located / where unsend is hosted. If you’re confused just use us-east-1
.
You can check available regions here
Once you logged in to unsend, it will prompt you add ses configuration.
- Add the region
- Add the callback url, which is basically the app url. Note this should be accesible from internet. This is how you get the delivery status of the emails.
- You don’t need to update the send rate, it’s automatically based on your account.
Step 4: Getting out of sandbox mode
Step 5: SMTP Proxy Server (Optional)
The SMTP proxy server is an optional component that allows applications to send emails through Unsend using standard SMTP protocol instead of the REST API. This is useful for legacy applications, email clients, or any software that needs to send emails via SMTP.
The complete source code for the SMTP proxy server is available at: unsend-dev/unsend/tree/main/apps/smtp-server
When to use the SMTP proxy:
- Legacy applications that only support SMTP
- Email clients like Thunderbird, Outlook, Apple Mail
- Applications that can’t easily integrate with REST APIs
- Third-party software that requires SMTP configuration
Docker Compose Setup
Create a docker-compose.yml
file for the SMTP server:
Run the SMTP server:
SMTP Configuration
To send emails through the proxy, configure your application with these SMTP settings:
- Host: Your server’s IP address or domain
- Ports: 25, 587 (STARTTLS), 465 (SSL/TLS), 2587, or 2465
- Username:
unsend
(or your customSMTP_AUTH_USERNAME
) - Password: Your Unsend API key
- Encryption: STARTTLS (ports 25, 587, 2587) or SSL/TLS (ports 465, 2465)
The SMTP proxy forwards all emails to your Unsend instance, so make sure your main Unsend application is running and accessible.
Ensure your firewall allows traffic on the SMTP ports you’re using. For production deployments, consider using non-standard ports (2587, 2465) to avoid conflicts.
Next steps
You’re all set up now.
- Setup a domain.
- Create an API key.
- Start sending emails.
If you have any questions, please join #self-host on discord.
A community member shared a short write-up on hosting Unsend with Coolify. Give it a read if you need another reference.