Skip to main content

How to use SendGrid as a Smarthost

Ausaf Lateef
  • Updated

Introduction

Many providers now block outbound connections on port 25, which means that a cPanel system would need to configure a smarthost to allow for outbound emails to function. This resource will go through how to set up a smarthost using a common 3rd-party mail provider, SendGrid.

 

Procedure

SendGrid has a free plan that allows for 40,000 emails to be sent through their system within the account's first 30 days. After the 30 days has concluded, the free plan only allows 100 emails per day.

1. Sign up for SendGrid, if you have not already done so.
New Account | Sendgrid

2. Log in to WHM as the root user. Once logged in, navigate to WHM > Service Configuration > Exim Configuration Manager > Advanced Editor. On this page, search for "Section: AUTH". In the text box, input the following:

sendgrid_login:
 driver = plaintext
 public_name = LOGIN
 client_send = : apikey : YOUR-SENDGRID-API-KEY

Notes:

  • You must replace "YOUR-SENDGRID-API-KEY" with your own generated API token within SendGrid. The token must have minimum permissions of 'Mail' to function correctly.
  • It is also possible to enter the route configuration in the ROUTERSTART or PREROUTERES section instead of POSTMAILCOUNT, but doing so will stop some mail limits from working. We advise you to use POSTMAILCOUNT unless you have a good reason not to.

3. Go to the "Section: POSTMAILCOUNT" section, and input the following in the text box:

  • v108 and above:
send_via_sendgrid:
 driver = manualroute
 domains = ! +local_domains
.ifdef SRSENABLED
 # if outbound, and forwarding has been done, use an alternate transport
 transport = ${if eq {$local_part@$domain} \
          {$original_local_part@$original_domain} \
          {sendgrid_smtp} {sendgrid_forwarded_smtp}}
.else
 transport = sendgrid_smtp
.endif
 route_list = "* smtp.sendgrid.net::587 byname"
 host_find_failed = defer
 no_more
  • v106 and below:
send_via_sendgrid:
 driver = manualroute
 domains = ! +local_domains
 transport = sendgrid_smtp
 route_list = "* smtp.sendgrid.net::587 byname"
 host_find_failed = defer
 no_more
  • If any domains are configured with manualmx entries, use the following "domains" line instead:
domains = ! +local_domains : ! +manualmx_domains

4. Add the following into the "Section: TRANSPORTSTART" text box:

sendgrid_smtp:
 driver = smtp
 hosts = smtp.sendgrid.net
 hosts_require_auth = $host_address
 hosts_require_tls = $host_address

4.1. If your server is running v108 or above, add the following into the "Section: TRANSPORTSTART" text box as well:

.ifdef SRSENABLED
sendgrid_forwarded_smtp:
 driver = smtp
 hosts = smtp.sendgrid.net
 hosts_require_auth = $host_address
 hosts_require_tls = $host_address
 max_rcpt = 1
 return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}}
.endif

5. Navigate to the bottom of the page, and click, "Save". This saves the changes that have been made and automatically restarts the Exim service.

6. Now try sending a test email, preferably from one of the Webmail applications, and verify that it is received. If the email gets queued on the server, you must examine the /var/log/exim_mainlog file to determine the cause of the issue.

 

Notes:

  • This guide is a task intended for system administrators. cPanel's Technical Analysts cannot provide assistance in configuring a server's smarthost setup.
  • Configuring a smarthost will cause all outbound emails to go through the configured provider. The scope of this document does not cover how to configure a subset of domains to go through a smarthost; this must be configured by the system administrator of the server.
  • A similar resource for setting up a smarthost with MailGun:
    How to use MailGun as a Smarthost

Related articles