Designs API
The Designs API offers the ability to manage assets stored in the Twilio SendGrid Design Library.
The Design Library is a feature-rich email layout tool and media repository. You can build designs for all your email needs, including Single Sends, Automations, and Dynamic Templates.
You can also duplicate and then modify one of the pre-built designs provided by Twilio SendGrid to get you started.
The Designs API provides a RESTful interface for creating new designs, retrieving a list of existing designs, duplicating or updating a design, and deleting a design.
Create Design
POST /v3/designs
Base url: https://api.sendgrid.com
This endpoint allows you to create a new design.
You can add a new design by passing data, including a string of HTML email content, to /designs. When creating designs from scratch, be aware of the styling constraints inherent to many email clients. For a list of best practices, see our guide to Cross-Platform Email Design.
The Design Library can also convert your design’s HTML elements into drag and drop modules that are editable in the Designs Library user interface. For more, visit the Design and Code Editor documentation.
Because the /designs endpoint makes it easy to add designs, you can create a design with your preferred tooling or migrate designs you already own without relying on the Design Library UI.
Authentication
- API Key
Headers
Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
Request Body
object
name
string
The name of the new design.
default: Duplicate: <original design name>editor
string
The editor used in the UI.
Allowed Values: code, designhtml_content
string
The HTML content of the Design.
maxLength: 1048576required
plain_content
string
Plain text content of the Design.
default: <generated from html_content if left empty>maxLength: 1048576generate_plain_content
boolean
If true, plain_content is always generated from html_content. If false, plain_content is not altered.
default: Truesubject
string
Subject of the Design.
maxLength: 5000categories
array[string]
The list of categories applied to the design
maxItems: 10uniqueItems: True{
"name": "Ahoy, Cake or Pie Cafe!",
"editor": "design",
"subject": "Getting Started",
"html_content": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\n<html data-editor-version=\"2\" class=\"sg-campaigns\" xmlns=\"http://www.w3.org/1999/xhtml\">\n <head>\n <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1\">\n <!--[if !mso]><!-->\n <meta http-equiv=\"X-UA-Compatible\" content=\"IE=Edge\">\n <!--<![endif]-->\n <!--[if (gte mso 9)|(IE)]>\n <xml>\n <o:OfficeDocumentSettings>\n <o:AllowPNG/>\n <o:PixelsPerInch>96</o:PixelsPerInch>\n </o:OfficeDocumentSettings>\n </xml>\n <![endif]-->\n <!--[if (gte mso 9)|(IE)]>\n <style type=\"text/css\">\n body {width: 600px;margin: 0 auto;}\n table {border-collapse: collapse;}\n table, td {mso-table-lspace: 0pt;mso-table-rspace: 0pt;}\n img {-ms-interpolation-mode: bicubic;}\n </style>\n<![endif]-->\n <style type=\"text/css\">\n body, p, div {\n font-family: arial,helvetica,sans-serif;\n font-size: 14px;\n }\n body {\n color: #000000;\n }\n body a {\n color: #1188E6;\n text-decoration: none;\n }\n p { margin: 0; padding: 0; }\n table.wrapper {\n width:100% !important;\n table-layout: fixed;\n -webkit-font-smoothing: antialiased;\n -webkit-text-size-adjust: 100%;\n -moz-text-size-adjust: 100%;\n -ms-text-size-adjust: 100%;\n }\n img.max-width {\n max-width: 100% !important;\n }\n .column.of-2 {\n width: 50%;\n }\n .column.of-3 {\n width: 33.333%;\n }\n .column.of-4 {\n width: 25%;\n }\n ul ul ul ul {\n list-style-type: disc !important;\n }\n ol ol {\n list-style-type: lower-roman !important;\n }\n ol ol ol {\n list-style-type: lower-latin !important;\n }\n ol ol ol ol {\n list-style-type: decimal !important;\n }\n @media screen and (max-width:480px) {\n .preheader .rightColumnContent,\n .footer .rightColumnContent {\n text-align: left !important;\n }\n .preheader .rightColumnContent div,\n .preheader .rightColumnContent span,\n .footer .rightColumnContent div,\n .footer .rightColumnContent span {\n text-align: left !important;\n }\n .preheader .rightColumnContent,\n .preheader .leftColumnContent {\n font-size: 80% !important;\n padding: 5px 0;\n }\n table.wrapper-mobile {\n width: 100% !important;\n table-layout: fixed;\n }\n img.max-width {\n height: auto !important;\n max-width: 100% !important;\n }\n a.bulletproof-button {\n display: block !important;\n width: auto !important;\n font-size: 80%;\n padding-left: 0 !important;\n padding-right: 0 !important;\n }\n .columns {\n width: 100% !important;\n }\n .column {\n display: block !important;\n width: 100% !important;\n padding-left: 0 !important;\n padding-right: 0 !important;\n margin-left: 0 !important;\n margin-right: 0 !important;\n }\n .social-icon-column {\n display: inline-block !important;\n }\n }\n </style>\n <!--user entered Head Start--><!--End Head user entered-->\n </head>\n <body>\n <center class=\"wrapper\" data-link-color=\"#1188E6\" data-body-style=\"font-size:14px; font-family:arial,helvetica,sans-serif; color:#000000; background-color:#FFFFFF;\">\n <div class=\"webkit\">\n <table cellpadding=\"0\" cellspacing=\"0\" border=\"0\" width=\"100%\" class=\"wrapper\" bgcolor=\"#FFFFFF\">\n <tr>\n <td valign=\"top\" bgcolor=\"#FFFFFF\" width=\"100%\">\n <table width=\"100%\" role=\"content-container\" class=\"outer\" align=\"center\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\">\n <tr>\n <td width=\"100%\">\n <table width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\">\n <tr>\n <td>\n <!--[if mso]>\n <center>\n <table><tr><td width=\"600\">\n <![endif]-->\n <table width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\" style=\"width:100%; max-width:600px;\" align=\"center\">\n <tr>\n <td role=\"modules-container\" style=\"padding:0px 0px 0px 0px; color:#000000; text-align:left;\" bgcolor=\"#FFFFFF\" width=\"100%\" align=\"left\"><table class=\"module preheader preheader-hide\" role=\"module\" data-type=\"preheader\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\" style=\"display: none !important; mso-hide: all; visibility: hidden; opacity: 0; color: transparent; height: 0; width: 0;\">\n <tr>\n <td role=\"module-content\">\n <p></p>\n </td>\n </tr>\n </table><table class=\"module\" role=\"module\" data-type=\"text\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\" style=\"table-layout: fixed;\" data-muid=\"41f90842-501c-4f08-96c9-17c0f74cb841\" data-mc-module-version=\"2019-10-22\">\n <tbody>\n <tr>\n <td style=\"padding:18px 0px 18px 0px; line-height:22px; text-align:inherit;\" height=\"100%\" valign=\"top\" bgcolor=\"\" role=\"module-content\"><div><div style=\"font-family: inherit; text-align: inherit\">Ahoy, World!</div><div></div></div></td>\n </tr>\n </tbody>\n </table><div data-role=\"module-unsubscribe\" class=\"module\" role=\"module\" data-type=\"unsubscribe\" style=\"color:#444444; font-size:12px; line-height:20px; padding:16px 16px 16px 16px; text-align:Center;\" data-muid=\"4e838cf3-9892-4a6d-94d6-170e474d21e5\"><div class=\"Unsubscribe--addressLine\"><p class=\"Unsubscribe--senderName\" style=\"font-size:12px; line-height:20px;\">{{Sender_Name}}</p><p style=\"font-size:12px; line-height:20px;\"><span class=\"Unsubscribe--senderAddress\">{{Sender_Address}}</span>, <span class=\"Unsubscribe--senderCity\">{{Sender_City}}</span>, <span class=\"Unsubscribe--senderState\">{{Sender_State}}</span> <span class=\"Unsubscribe--senderZip\">{{Sender_Zip}}</span></p></div><p style=\"font-size:12px; line-height:20px;\"><a class=\"Unsubscribe--unsubscribeLink\" href=\"{{{unsubscribe}}}\" target=\"_blank\" style=\"\">Unsubscribe</a> - <a href=\"{{{unsubscribe_preferences}}}\" target=\"_blank\" class=\"Unsubscribe--unsubscribePreferences\" style=\"\">Unsubscribe Preferences</a></p></div></td>\n </tr>\n </table>\n <!--[if mso]>\n </td>\n </tr>\n </table>\n </center>\n <![endif]-->\n </td>\n </tr>\n </table>\n </td>\n </tr>\n </table>\n </td>\n </tr>\n </table>\n </div>\n </center>\n </body>\n </html>",
"plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )"
}Responses
object
id
string
ID of the Design.
format: uuidupdated_at
string
Datetime that Design was last updated.
format: ISO 8601 date-timecreated_at
string
Datetime that Design was created.
format: ISO 8601 date-timethumbnail_url
string
A Thumbnail preview of the template's html content.
name
string
The name of the new design.
default: Duplicate: <original design name>editor
string
The editor used in the UI.
Allowed Values: code, designhtml_content
string
The HTML content of the Design.
maxLength: 1048576required
plain_content
string
Plain text content of the Design.
default: <generated from html_content if left empty>maxLength: 1048576generate_plain_content
boolean
If true, plain_content is always generated from html_content. If false, plain_content is not altered.
default: Truesubject
string
Subject of the Design.
maxLength: 5000categories
array[string]
The list of categories applied to the design
maxItems: 10uniqueItems: True{
"result": [
{
"id": "3247eaea-c912-42a3-b0bc-60bdaf210396",
"name": "Welcome Email",
"generate_plain_content": true,
"thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png",
"subject": "Welcom to the Cake or Pie Cafe",
"created_at": "2021-04-09T17:29:46Z",
"updated_at": "2021-04-09T17:29:55Z",
"editor": "code",
"categories": [
"welcome",
"new customer"
]
},
{
"id": "02dfd792-f31f-439a-a79e-5c47fbcfdbac",
"name": "Monthly Promo",
"generate_plain_content": true,
"thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png",
"subject": "Free Dozen Cupcakes",
"created_at": "2021-04-09T17:29:21Z",
"updated_at": "2021-04-09T17:29:42Z",
"editor": "design",
"categories": [
"promo",
"coupon"
]
},
{
"id": "e54be823-19ef-4c6f-8b60-efd7514f492d",
"name": "Duplicate: Ingrid & Anders",
"generate_plain_content": true,
"thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png",
"subject": "Welcome to Ingrid & Anders!",
"created_at": "2020-10-09T17:33:46Z",
"updated_at": "2021-04-07T19:57:52Z",
"editor": "design",
"categories": []
}
],
"_metadata": {
"self": "https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I",
"count": 3
},
"name": "Ahoy, Cake or Pie Cafe!",
"editor": "design",
"subject": "Getting Started",
"html_content": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\n<html data-editor-version=\"2\" class=\"sg-campaigns\" xmlns=\"http://www.w3.org/1999/xhtml\">\n <head>\n <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1\">\n <!--[if !mso]><!-->\n <meta http-equiv=\"X-UA-Compatible\" content=\"IE=Edge\">\n <!--<![endif]-->\n <!--[if (gte mso 9)|(IE)]>\n <xml>\n <o:OfficeDocumentSettings>\n <o:AllowPNG/>\n <o:PixelsPerInch>96</o:PixelsPerInch>\n </o:OfficeDocumentSettings>\n </xml>\n <![endif]-->\n <!--[if (gte mso 9)|(IE)]>\n <style type=\"text/css\">\n body {width: 600px;margin: 0 auto;}\n table {border-collapse: collapse;}\n table, td {mso-table-lspace: 0pt;mso-table-rspace: 0pt;}\n img {-ms-interpolation-mode: bicubic;}\n </style>\n<![endif]-->\n <style type=\"text/css\">\n body, p, div {\n font-family: arial,helvetica,sans-serif;\n font-size: 14px;\n }\n body {\n color: #000000;\n }\n body a {\n color: #1188E6;\n text-decoration: none;\n }\n p { margin: 0; padding: 0; }\n table.wrapper {\n width:100% !important;\n table-layout: fixed;\n -webkit-font-smoothing: antialiased;\n -webkit-text-size-adjust: 100%;\n -moz-text-size-adjust: 100%;\n -ms-text-size-adjust: 100%;\n }\n img.max-width {\n max-width: 100% !important;\n }\n .column.of-2 {\n width: 50%;\n }\n .column.of-3 {\n width: 33.333%;\n }\n .column.of-4 {\n width: 25%;\n }\n ul ul ul ul {\n list-style-type: disc !important;\n }\n ol ol {\n list-style-type: lower-roman !important;\n }\n ol ol ol {\n list-style-type: lower-latin !important;\n }\n ol ol ol ol {\n list-style-type: decimal !important;\n }\n @media screen and (max-width:480px) {\n .preheader .rightColumnContent,\n .footer .rightColumnContent {\n text-align: left !important;\n }\n .preheader .rightColumnContent div,\n .preheader .rightColumnContent span,\n .footer .rightColumnContent div,\n .footer .rightColumnContent span {\n text-align: left !important;\n }\n .preheader .rightColumnContent,\n .preheader .leftColumnContent {\n font-size: 80% !important;\n padding: 5px 0;\n }\n table.wrapper-mobile {\n width: 100% !important;\n table-layout: fixed;\n }\n img.max-width {\n height: auto !important;\n max-width: 100% !important;\n }\n a.bulletproof-button {\n display: block !important;\n width: auto !important;\n font-size: 80%;\n padding-left: 0 !important;\n padding-right: 0 !important;\n }\n .columns {\n width: 100% !important;\n }\n .column {\n display: block !important;\n width: 100% !important;\n padding-left: 0 !important;\n padding-right: 0 !important;\n margin-left: 0 !important;\n margin-right: 0 !important;\n }\n .social-icon-column {\n display: inline-block !important;\n }\n }\n </style>\n <!--user entered Head Start--><!--End Head user entered-->\n </head>\n <body>\n <center class=\"wrapper\" data-link-color=\"#1188E6\" data-body-style=\"font-size:14px; font-family:arial,helvetica,sans-serif; color:#000000; background-color:#FFFFFF;\">\n <div class=\"webkit\">\n <table cellpadding=\"0\" cellspacing=\"0\" border=\"0\" width=\"100%\" class=\"wrapper\" bgcolor=\"#FFFFFF\">\n <tr>\n <td valign=\"top\" bgcolor=\"#FFFFFF\" width=\"100%\">\n <table width=\"100%\" role=\"content-container\" class=\"outer\" align=\"center\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\">\n <tr>\n <td width=\"100%\">\n <table width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\">\n <tr>\n <td>\n <!--[if mso]>\n <center>\n <table><tr><td width=\"600\">\n <![endif]-->\n <table width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\" style=\"width:100%; max-width:600px;\" align=\"center\">\n <tr>\n <td role=\"modules-container\" style=\"padding:0px 0px 0px 0px; color:#000000; text-align:left;\" bgcolor=\"#FFFFFF\" width=\"100%\" align=\"left\"><table class=\"module preheader preheader-hide\" role=\"module\" data-type=\"preheader\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\" style=\"display: none !important; mso-hide: all; visibility: hidden; opacity: 0; color: transparent; height: 0; width: 0;\">\n <tr>\n <td role=\"module-content\">\n <p></p>\n </td>\n </tr>\n </table><table class=\"module\" role=\"module\" data-type=\"text\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\" style=\"table-layout: fixed;\" data-muid=\"41f90842-501c-4f08-96c9-17c0f74cb841\" data-mc-module-version=\"2019-10-22\">\n <tbody>\n <tr>\n <td style=\"padding:18px 0px 18px 0px; line-height:22px; text-align:inherit;\" height=\"100%\" valign=\"top\" bgcolor=\"\" role=\"module-content\"><div><div style=\"font-family: inherit; text-align: inherit\">Ahoy, World!</div><div></div></div></td>\n </tr>\n </tbody>\n </table><div data-role=\"module-unsubscribe\" class=\"module\" role=\"module\" data-type=\"unsubscribe\" style=\"color:#444444; font-size:12px; line-height:20px; padding:16px 16px 16px 16px; text-align:Center;\" data-muid=\"4e838cf3-9892-4a6d-94d6-170e474d21e5\"><div class=\"Unsubscribe--addressLine\"><p class=\"Unsubscribe--senderName\" style=\"font-size:12px; line-height:20px;\">{{Sender_Name}}</p><p style=\"font-size:12px; line-height:20px;\"><span class=\"Unsubscribe--senderAddress\">{{Sender_Address}}</span>, <span class=\"Unsubscribe--senderCity\">{{Sender_City}}</span>, <span class=\"Unsubscribe--senderState\">{{Sender_State}}</span> <span class=\"Unsubscribe--senderZip\">{{Sender_Zip}}</span></p></div><p style=\"font-size:12px; line-height:20px;\"><a class=\"Unsubscribe--unsubscribeLink\" href=\"{{{unsubscribe}}}\" target=\"_blank\" style=\"\">Unsubscribe</a> - <a href=\"{{{unsubscribe_preferences}}}\" target=\"_blank\" class=\"Unsubscribe--unsubscribePreferences\" style=\"\">Unsubscribe Preferences</a></p></div></td>\n </tr>\n </table>\n <!--[if mso]>\n </td>\n </tr>\n </table>\n </center>\n <![endif]-->\n </td>\n </tr>\n </table>\n </td>\n </tr>\n </table>\n </td>\n </tr>\n </table>\n </div>\n </center>\n </body>\n </html>",
"plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )"
}object
errors
array[object]
message
string
required
field
string
required
error_id
string
required
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
