Now that you've sent a test SMTP email with Telnet, and integrated with SendGrid, it's time to build content.
The Twilio SendGrid SMTP service allows you to pass SendGrid a JSON string with as many SMTP objects as you want. This functionality is made possible by including a header named X-SMTPAPI. This page provides instructions for using the X-SMTPAPI to modify and control your mail send.
The X-SMTPAPI is a powerful way to modify your SMTP messages. However, there are several things to keep in mind when using the header.
\u
escape character. For example, the Unicode
á
character will look like this:
\u00E1
.
1{2"to": ["example@example.com", "example@example.com"],3"sub": {4"%name%": ["Ben", "Joe"],5"%role%": ["%sellerSection%", "%buyerSection%"]6},7"category": ["Orders"],8"unique_args": {9"orderNumber": "12345",10"eventID": "6789"11},12"filters": {13"footer": {14"settings": {15"enable": 1,16"text/plain": "Thank you for your business"17}18}19},20"send_at": 140934851321}
You can customize the emails you send via SMTP by using different settings (also referred to as filters).
The X-SMTPAPI header is a JSON-encoded object (key-value pairs) consisting of several sections. Below are examples of JSON strings using each section.
Schedule your email send time using the send_at
parameter within your X-SMTPAPI header. Set the value of send_at
formatted as a UNIX timestamp.
1{2"send_at": 14093485133}
For more information, see our scheduling parameters documentation.
It is possible to simulate blind carbon copy (BCC) behavior using SMTP with or without the X-SMTPAPI header. The concept of BCC exists outside of SMTP as defined by RFC 5321.
When sending email with SMTP, all recipients are listed using SMTP's RCPT (recipient) command. In addition to the sender, which is set with SMTP's MAIL command, these RCPT addresses can be thought of as part of the message envelope—they instruct sending email servers where to deliver the message. These addresses are not designated as carbon copy (CC), BCC, or another type of recipient—they are all just recipients.
The SMTP DATA command follows the MAIL and RCPT commands in an SMTP transaction. The DATA command allows you to insert message headers, which can be thought of as portions of the email body or the text inside the envelope. The DATA command is what allows you to create BCC behavior using SMTP without the X-SMTPAPI.
The following code shows an example of an SMTP transaction with BCC behavior. How this example achieves BCC behavior is explained following the example.
1235 Authentication successful2MAIL FROM:tiramisu@example.com3250 Sender address accepted4RCPT TO:person1@sendgrid.com5250 Recipient address accepted6RCPT TO:person2@sendgrid.com7250 Recipient address accepted8DATA9354 Continue10From: "Tira Misu" <tiramisu@example.com>11To: <person1@sendgrid.com>12Subject: Test message subject13This is the test message body.14.15250 Ok: queued as Yo60h6C5ScGPeP5fUWU3Kw
Notice that there are two recipients designated by RCPT commands, "person1@sendgrid.com" and "person2@sendgrid.com." These addresses are both part of the message envelope.
In the DATA command, there is also a "To" header. This header lists only "person1@sendgrid.com." This is where differentiating between the envelop "To" (RCPT TO) and header "To" becomes important. The header "To" set in the DATA command does not tell the sending email server to deliver the message to any address, only the RCPT or envelop "To" does this. The header "To" instead provides recipients with a friendly display of any addresses included in the "To" header.
To achieve BCC behavior, you can deliver a message to a recipient by adding them in a RCPT but omit their address from the header "To". The message will be delivered to each RCPT address, but only the addresses listed in the header "To" will be visible to other recipients.
In the previous code sample, "person2@sendgrid.com" will be treated like a BCC address because that address is not included in the header "To." The "person1@sendgrid.com" is listed in the header "To" and will therefore be visible to other recipients of the message. This means both recipients receive the message, but recipient2@sendgrid.com is not visible to recipient1@sendgrid.com while recipient1@sendgrid.com is visible to recipient2@sendgrid.com.
By omitting any addresses from the header "To," you will be hiding them from the other recipients and therefore treating them like BCC recipients.
The following code shows an example of an SMTP transaction with BCC behavior using the X-SMTPAPI header. How this example achieves BCC behavior is explained following the example.
1235 Authentication successful2MAIL FROM:tiramisu@example.com3250 Sender address accepted4RCPT TO:sender@sendgrid.com5250 Recipient address accepted6DATA7354 Continue8x-smtpapi: {"to":["person1@sendgrid.com","person2@sendgrid.com"]}9From: "Tira Misu" <tiramisu@example.com>10Subject: This is a test11Body of test message.12.13250 Ok: queued as uKIPst3rQtCl_hLVB9RvEw
Using the X-SMTPAPI header achieves BCC behavior in a slightly different way than by omitting addresses from a "To" header. The X-SMTPAPI header's "to" field allows you to set multiple recipients in a JSON array.
1{2"to": ["person1@sendgrid.com", "person2@sendgrid.com"]3}
When SendGrid receives the message and parses the X-SMTPAPI header, it will treat each recipient address in the X-SMTPAPI "to" field as a separate RCTP TO or envelope address. This means each recipient will receive the same DATA content, but with an added friendly display "to" header set to its own address. A single recipient in the X-SMTPAPI "to" field in the previous code sample will eventually look something like the following example.
1235 Authentication successful2MAIL FROM:test@example.com3250 Sender address accepted4RCPT TO:person1@sendgrid.com5250 Recipient address accepted
The addresses in the X-SMTPAPI "to" field are not duplicated in a header "To," for all recipients. Only the individual recipient is included in the header "To" for each messages (Each recipient sees only their own address). The additional recipients will therefore not be visible to each recipient of the message.
You can specify an unsubscribe group for an email sent via SMTP by including the asm_group_id
parameter in your X-SMTPAPI header. Set the value of asm_group_id
to the numerical ID of the group you would like to use.
1{2"asm_group_id": 13}
For more information, see our suppression groups documentation.
Categories allow you to track your emails according to broad topics that you define, like "Weekly Newsletter" or "Confirmation Email". Define the category by using the category
parameter within your X-SMTPAPI header:
1{2"category": "Example Category"3}
For more information, see our categories documentation.
Categories should only be used for broad topics. To attach unique identifiers, please use unique arguments.
Use unique arguments 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.
Categories and Unique Arguments will be stored as a "Not PII" field and may be used for counting or other operations as SendGrid runs its systems. These fields generally cannot be redacted or removed. You should take care not to place PII in this field. SendGrid does not treat this data as PII, and its value may be visible to SendGrid employees, stored long-term, and may continue to be stored after you have left SendGrid's platform.
SMTP Filters can be used for turning on or off a number of different features for your sending. For example, you can turn on open or click tracking on a per-send basis.
For more information, see our SMTP Filters documentation.
IP Pools can be used to send you mail over a specific group of IPs. It is common to create different pools for transactional and marketing email.
For more information, see our IP Pools documentation.
1{2"ip_pool": "pool_name"3}