Rate this page:

Section Tags

Due to low usage, this setting has been deprecated and has been removed. Click here for more information.

Section tags allow you to substitute in content in an SMTP message. Section tags are similar to substitution tags but are specific to the message, and not the recipient. You have to have a substitution tag value for each recipient, but you can have any number of section tags. Section tags can then contain Substitution tags for the recipient if needed. Section tags have to be contained within a Substitution tag since SendGrid needs to know which data to populate for the recipient. See the Section Tag Example Walkthrough below.

It's possible and acceptable to use only Substitution tags. However, that method is not DRY, and you may come against message size limitations.

When passing section please make sure to only use strings as shown in our examples. Any other type could result in unintended behavior.

The format of the SMTP API section tag has the form:

{
  "section": {
    ":sectionName1": "section 1 text",
    ":sectionName2": "section 2 text"
  }
}

How you flag your section tags may depend on the library you use to create your SMTP connection, the language you are writing your code in, or any intermediate mail servers that your servers will send mail through. In some cases -subVal- may be the best choice while in other cases, %subVal%, #subVal#, or :subVal may make more sense. The flag doesn't matter, as long as it's a unique string.

Do not use spaces inside your section or substitution tags! For example: %first name%. The space breaks the string.

Do not nest section tags in sections! This causes your section to not be replaced.

Section Tag Walkthrough

Message body sent to SendGrid:

<html>
  <body>
    Hi :salutation,<br />
    Thanks so much for joining us at our event!

    <p>
      You have registered for the following event:<br />
      :event_details.
    </p>

    Thanks,<br />
    The SendGrid Team
  </body>
</html>

The accompanying X-SMTPAPI JSON header would look like:

{
  "to": [
    "example1@example.com",
    "example2@example.com",
    "example3@example.com"
  ],
  "sub": {
    ":salutation": [":female", ":male", ":neutral"],
    ":name": ["Alice", "Bob", "Casey"],
    ":event_details": [":event1", ":event2", ":event1"],
    ":event_date": ["Jan 1", "Feb 14", "Aug 11"]
  },
  "section": {
    ":male": "Mr. :name",
    ":female": "Ms. :name",
    ":neutral": ":name",
    ":event1": "New User Event on :event_date",
    ":event2": "Veteran User Appreciation on :event_date"
  }
}

Alice receives:

<html>
  <body>
    Hi Ms. Alice,<br />
    Thanks so much for joining us at our event!

    <p>
      You have registered for the following event:<br />
      New User Event on Jan 1.
    </p>

    Thanks,<br />
    The SendGrid Team
  </body>
</html>

Bob receives:

<html>
  <body>
    Hi Mr. Bob,<br />
    Thanks so much for joining us at our event!

    <p>
      You have registered for the following event:<br />
      Veteran User Appreciation on Feb 14.
    </p>

    Thanks,<br />
    The SendGrid Team
  </body>
</html>

Casey receives:

<html>
  <body>
    Hi Casey,<br />
    Thanks so much for joining us at our event!

    <p>
      You have registered for the following event:<br />
      New User Event on Aug 11.
    </p>

    Thanks,<br />
    The SendGrid Team
  </body>
</html>

Additional Resources

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more