DEV Community

Tanvir Rahman
Tanvir Rahman

Posted on

📬 Setting Up Postfix with SendGrid Relay on Ubuntu: A Step-by-Step Guide

#linux #postfix #sendgrid #mailserver

If you’ve ever tried to send email directly from a Linux server, you know it can be a hassle—especially when dealing with deliverability and authentication. Fortunately, with Postfix and a reliable SMTP provider like SendGrid, you can offload the heavy lifting and ensure your emails land safely in inboxes.

In this guide, I’ll walk you through how to configure Postfix to relay mail through SendGrid, complete with authentication, sender rewriting, and testing.

🛠️ Prerequisites

  • A Linux server (tested on Ubuntu)
  • A SendGrid account and SMTP credentials
  • Root or sudo access
  • Basic comfort with the command line

✅ Step 1: Install Postfix
Let’s start by installing Postfix non-interactively to avoid configuration prompts:

DEBIAN_FRONTEND=noninteractive sudo apt-get install -y postfix
Enter fullscreen mode Exit fullscreen mode

🔐 Step 2: Set Up SASL Authentication for SendGrid
To authenticate with SendGrid’s SMTP server, we’ll create a file containing your credentials:

echo "[smtp.sendgrid.net]:587 username:password" | sudo tee /etc/postfix/sasl_passwd
sudo chmod 600 /etc/postfix/sasl_passwd
sudo postmap /etc/postfix/sasl_passwd
Enter fullscreen mode Exit fullscreen mode

Replace username:password with your actual SendGrid credentials (your username is usually "apikey", and the password is your generated API key).

📨 Step 3: Configure Sender Canonical Mapping
Sometimes you want all outgoing emails to appear as if they came from a specific address. This is where sender_canonical comes in.

echo "/.+@mail\.example\.com/ fromAddress@example.com
/^root@.*/ fromAddress@example.com
/@.*/ fromAddress@example.com" | sudo tee /etc/postfix/sender_canonical
sudo postmap /etc/postfix/sender_canonical
Enter fullscreen mode Exit fullscreen mode

These regex patterns help normalize the sender addresses. For instance, even if an internal process sends an email as root@mail.example.com, it will appear to come from fromAddress@example.com.

✉️ Step 4: (Optional) Create a Generic Mapping File
If you’re rewriting sender addresses more broadly, this is useful. Otherwise, you can skip it.

echo "username@example.com relayuser@sendgrid.net" | sudo tee /etc/postfix/generic
sudo postmap /etc/postfix/generic
Enter fullscreen mode Exit fullscreen mode

Make sure this matches your intended email addresses.

⚙️ Step 5: Configure Postfix (main.cf)
Now for the core config. We’ll overwrite the main.cf file to define everything, including SendGrid relay, network settings, and sender rewriting.

sudo tee /etc/postfix/main.cf > /dev/null << 'EOL'
# Basic Settings
compatibility_level = 2
queue_directory = /var/spool/postfix
command_directory = /usr/sbin
daemon_directory = /usr/lib/postfix/sbin
data_directory = /var/lib/postfix
mail_owner = postfix

# Network Settings
myhostname = mail.example.com
mydomain = example.com
myorigin = example.com
inet_interfaces = all
inet_protocols = ipv4
mydestination = $myhostname, localhost.$mydomain, localhost

# SendGrid Relay Configuration
relayhost = [smtp.sendgrid.net]:587
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_tls_security_level = none

# Additional Settings
smtpd_banner = $myhostname ESMTP
biff = no
append_dot_mydomain = no
readme_directory = no

# Sender Settings
smtp_generic_maps = hash:/etc/postfix/generic

# SMTP Client Restrictions

# Message Size Limits
message_size_limit = 10240000
mailbox_size_limit = 0

# Local Recipient Settings
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
local_recipient_maps = proxy:unix:passwd.byname $alias_maps
local_transport = local:$myhostname

# Network Security
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
sender_canonical_maps = regexp:/etc/postfix/sender_canonical
EOL
Enter fullscreen mode Exit fullscreen mode

Adjust myhostname, mydomain, and fromAddress@example.com to match your real domain and sending address.

👥 Step 6: Update Aliases and Restart Postfix
Make sure aliases are recognized and apply the config changes:

sudo newaliases && sudo systemctl restart postfix && sudo systemctl status postfix
Enter fullscreen mode Exit fullscreen mode

You should see Active: active (running) in the output.

🧪 Step 7: Send a Test Email
Let’s test if your relay setup is working:

echo "This is a test email from Postfix with SendGrid relay" | mail -s "Test Email from Postfix" -r fromAddress@example.com toAddress@example.com
Enter fullscreen mode Exit fullscreen mode

Make sure mailutils is installed if this fails:

sudo apt-get install -y mailutils
Enter fullscreen mode Exit fullscreen mode

📄 Step 8: Monitor Logs
To debug or confirm delivery, keep an eye on the logs:

tail -f /var/log/mail.log
Enter fullscreen mode Exit fullscreen mode

This log is your go-to source for tracking down any delivery issues.

📂 Bonus: View Postfix Config and Files
Here’s a snapshot of how your /etc/postfix/ directory should look after setup:

ls -la /etc/postfix/ && echo -e "\nMain config file contents:" && cat /etc/postfix/main.cf
Enter fullscreen mode Exit fullscreen mode

You should see key files like:

  • main.cf – your main configuration
  • sasl_passwd & sasl_passwd.db – credentials for SendGrid
  • sender_canonical & sender_canonical.db – for rewriting sender addresses
  • generic & generic.db – for optional address rewriting

✅ Summary
You’ve now got a reliable, authenticated Postfix setup using SendGrid’s SMTP relay. Here's what you've accomplished:

  • Installed and configured Postfix
  • Authenticated with SendGrid securely
  • Rewritten sender addresses as needed
  • Sent and verified test emails
  • Monitored logs and verified configuration

This setup is great for sending system alerts, contact form emails, or even automating reports via cron.

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.