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.