Table of Contents

What is SMTP?

SMTP, or simple mail transfer protocol, is a quick and easy way to send email from one server to another. SendGrid provides a 3rd party SMTP service that allows you to deliver your email via our server instead of your own client or server.

For a deeper dive into what SMTP is, what the benefits of sending email via SMTP are, and how SendGrid can help, see the SMTP Service Crash Course on our blog.

How to Send Email via SMTP

  1. Create an API Key with at least “Mail” permissions.
  2. Set the server host in your email client or application to smtp.sendgrid.net.
    • This setting is sometimes referred to as the external SMTP server or the SMTP relay.
  3. Set your username to apikey.
  4. Set your password to the API key generated in step 1.
  5. Set the port to 587.

Rate Limits

  • You may send up to 100 messages per SMTP connection.
  • You may open up to 10 concurrent connections from a single server.

Related Articles

Customizing Your Send

Filters

You can customize the emails you send via SMTP by using different settings (also referred to as filters). These settings are specified within the X-SMTPAPI header.

For example, to send a blind carbon copy (BCC) of your email to the address example@example.com, include the following in your X-SMTPAPI header:

1
2
3
4
5
6
7
8
9
10
{
  "filters" : {
    "bcc" : {
      "settings" : {
        "enable" : 1,
        "email" : "example@example.com"
      }
    }
  }
}

For a complete list of settings that can be enabled via the X-SMTPAPI header, see our SMTP documentation.

Scheduling Your Send

You can easily schedule when your email will be sent by using the send_at parameter within your X-SMTPAPI header. Set the value of send_at to a UNIX timestamp representing the time that you want your email to be sent.

1
2
3
{
  "send_at": 1409348513
}

For more information, see our scheduling parameters documentation.

Substitution Tags

Substitution tags allow you to dynamically insert specific content relevant to each of your recipients, such as their first and last names.

For example, to use a substitution tag to replace the first name of your recipient, insert the tag -name- in the HTML of your message:

1
2
3
4
5
6
7
8
<html>
  <head></head>
  <body>
    <p>Hello -name-,<br>
        The body of your email would go here...
    </p>
  </body>
</html>

To define the value that will replace the -name- tag, define the following in your X-SMTPAPI header:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "to": [
    "john.doe@example.com",
    "jane.doe@hotmail.com"
  ],
  "sub": {
    "-name-": [
      "John",
      "Jane"
    ]
  }
}

For more information, see our substitution tags documentation.

Section Tags

Section tags are similar to substitution tags, but rather than replace tags with content for each individual recipient, section tags allow you to replace a tag with more generic content— like a salutation.

For more information, see our section tags documentation.

Suppression Groups

You can easily specify an unsubscribe group for an email sent via SMTP by including the asm_group_id parameter in your X-SMTPAPI header. Simply set the value of asm_group_id to the numerical ID of the group you would like to use.

1
2
3
{
  "asm_group_id": 1
}

For more information, see our suppression groups documentation.

Categories

Categories allow you to track your emails according to broad topics that you define, like “Weekly Newsletter” or “Confirmation Email”. Simply define the category by using the category parameter within your X-SMTPAPI header:

1
2
3
{
  "category": "Example Category"
}

For more information, see our categories documentation.

Categories should only be used for broad topics. To attach unique identifiers, please use unique arguments.

Unique Arguments

Unique arguments are a very useful way for you to track your emails based on specific identifiers unique to individual messages. Unique arguments can be retrieved via SendGrid’s Event Webhook or your email activity page.

For more information, see our unique arguments documentation.