Content Services API Reference

The Content Services API Reference provides a comprehensive guide to utilizing the Content Services API, which leverages the REST architecture and HTTP protocol for making API calls. This reference document outlines the available collections, including /message, /page, /popup, /amp, /template, and /ai, detailing the resources for each collection. For every resource, this document includes its description, parameters, and example responses and requests.

API Key

To use the Content Services API you will first need to obtain a your API Key from the Beefree SDK Console.

To obtain an API Key, take the following steps:

Log into the Beefree SDK Console
Locate the application that you wish to work with, and click on Details
Locate the Content Services API section and click Create New API Key
Acknowledge the message that reminds you that if you exceed the number of API calls included in your plan, you may be charged for overages and click Create Key

Your API key will appear under the Content services API section of your application details.

The Content Services API uses API Keys to authenticate requests for resources. You can manage your API Keys within the Beefree SDK Console. All requests must be made over HTTPS and contain the following HTTP Header:

Authorization: Bearer {token}

Rate Limits

API requests rate limits exist independently of API key’s monthly usage allowance.

By default, the API has the following rate limits:

Per minute: 500 requests
Per second: 100 requests
X-Rate-Limit: An integer representing the total number of requests available per cycle. Exceeding the limit per cycle results in a 429 error. (e.g. 500)
X-Rate-Limit-Remaining: An integer representing the number of remaining requests before the next cycle begins, and the count resets. (e.g. 100)
X-Rate-Limit-Reset: A Unix timestamp representing the time the next cycle will begin, and the count will reset.
Retry-After: A Unix timestamp representing the time the application may resume submitting requests.

API Root

All API access is over HTTPS, and accessed from the following URL:

https://api.getbee.io/v1/{collection}/{resource}

Collections

The following table lists the available collection option and corresponding resources for each collection.

Collection

Available Resources

/message

html, pdf, images, merge, index, plain-text

/page

html, pdf, images, merge, index

/popup

html

/amp

html

/template

brand

/ai

metadata, sms, summary

/conversion

email-to-page, page-to-email

Example URLs

The following table provides a few examples of URLs you can use to make specific types of requests.

Type

Action

Example URL

Request HTML for email

https://api.getbee.io/v1/message/html

Landing Page

Request HTML for a landing page

https://api.getbee.io/v1/page/html

Popup

Request HTML for a popup

https://api.getbee.io/v1/popup/html

AMP

Request HTML for AMP

https://api.getbee.io/v1/amp/html

Resources

The following section provides detailed information for each of the resources associated with each collection mentioned in the previous section.

HTML

URL: https://api.getbee.io/v1/{collection}/html

Transform JSON Template to HTML

post

Transform a JSON template into an HTML response.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection ID or name

Body

beautifyHtmlEnabledbooleanOptional

Flag to return beautified HTML

languagestringOptional

For multi-language templates, sets the output language using a valid language code

Responses

200

The HTML response

text/html

post

/v1/{collection}/html

POST /v1/{collection}/html HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1017

{
  "beautifyHtmlEnabled": true,
  "language": "text",
  "page": {
    "body": {
      "container": {
        "style": {
          "backgroundColor": "#FFFFFF"
        }
      },
      "content": {
        "computedStyle": {
          "linkColor": "#FF819C",
          "messageBackgroundColor": "transparent",
          "messageWidth": "675px"
        },
        "style": {
          "color": "#000000",
          "fontFamily": "Arial, Helvetica Neue, Helvetica, sans-serif"
        }
      }
    },
    "webFonts": [
      {
        "fontFamily": "'Montserrat', 'Trebuchet MS', 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', Tahoma, sans-serif",
        "name": "Montserrat",
        "url": "https://fonts.googleapis.com/css2?family=Montserrat:wght@400;700&display=swap"
      }
    ],
    "description": "BF-ecommerce-template",
    "rows": [
      {
        "columns": [
          {
            "gridColumns": 6,
            "modules": [
              {
                "moduleDescriptor": {
                  "computedStyle": {
                    "cssClass": "left fixedwidth",
                    "width": "287px"
                  },
                  "image": {
                    "alt": "Image",
                    "height": "142px",
                    "href": "https://beefree.io",
                    "src": "https://ih1.redbubble.net/image.4902607927.7016/flat,750x,075,f-pad,750x1000,f8f8f8.jpg",
                    "width": "546px"
                  }
                }
              }
            ]
          }
        ]
      }
    ],
    "template": {
      "name": "template-base",
      "type": "basic",
      "version": "2.0.0"
    },
    "title": "BF-ecommerce-template"
  }
}

200

The HTML response

<!DOCTYPE html>
<html lang="en">
<head>
<title></title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<style>/* Styles here */</style>
</head>
<body>
<!-- HTML content here -->
</body>
</html>

Plain Text

Endpoint: /message/plain-text

Generate Plain Text

post

This endpoint accepts a JSON template to create a plain text version of an email.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

languagestringOptional

Optional. The output language for multi-language templates.

Responses

200

A successful response with the plain text document.

text/plain

400

Invalid input or request parameters.

post

/v1/message/plain-text

POST /v1/message/plain-text HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1241

{
  "language": "it-IT",
  "page": {
    "body": {
      "container": {
        "style": {
          "background-color": "#fff",
          "background-image": "none",
          "background-position": "top left",
          "background-repeat": "no-repeat",
          "background-size": "auto"
        }
      },
      "content": {
        "computedStyle": {
          "linkColor": "#8a3b8f",
          "messageBackgroundColor": "transparent",
          "messageWidth": "650px"
        },
        "style": {
          "color": "#000000",
          "font-family": "Lato, Tahoma, Verdana, Segoe, sans-serif"
        }
      }
    },
    "rows": [
      {
        "columns": [
          {
            "grid-columns": 12,
            "modules": [
              {
                "descriptor": {
                  "computedStyle": {
                    "align": "center",
                    "hideContentOnMobile": false
                  },
                  "divider": {
                    "style": {
                      "border-top": "0px solid transparent",
                      "height": "10px",
                      "width": "100%"
                    }
                  },
                  "style": {
                    "padding-bottom": "0px",
                    "padding-left": "0px",
                    "padding-right": "0px",
                    "padding-top": "0px"
                  }
                },
                "locked": false,
                "type": "mailup-bee-newsletter-modules-divider",
                "uuid": "b89c3d25-dbec-439a-8ad1-4939a28678e9"
              }
            ],
            "style": {
              "background-color": "transparent",
              "border-bottom": "0px solid transparent",
              "border-left": "0px solid transparent",
              "border-right": "0px solid transparent",
              "border-top": "0px solid transparent",
              "padding-bottom": "0px",
              "padding-left": "0px",
              "padding-right": "0px",
              "padding-top": "0px"
            },
            "uuid": "3bd72010-5175-4326-b848-8beacea852d6"
          }
        ]
      }
    ],
    "template": {
      "name": "template-base",
      "type": "basic",
      "version": "2.0.0"
    },
    "title": ""
  }
}

[BEE Pro Logo](https://beefree.io/) 

***************************** 

Hi 😊 **Would you be interested to participate in a user research project with us?**

PDF

URL: https://api.getbee.io/v1/{collection}/pdf

Generate PDF

post

This endpoint accepts HTML and settings to generate a PDF document and provides a URL for the PDF.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

file_typestring · enumRequired

The file type for the output.

Default: PDFPossible values:

htmlstringRequired

A full HTML document to be transformed into a PDF.

page_orientationstring · enumRequired

The orientation of the PDF page.

Default: landscapePossible values:

page_sizestring · enumRequired

The size of the PDF page.

Default: letterPossible values:

Responses

200

A successful response with the PDF document URL.

application/json

400

Invalid input or request parameters.

post

/v1/{collection}/pdf

POST /v1/{collection}/pdf HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 477

{
  "html": "<!DOCTYPE html><html lang='en'><head><meta charset='UTF-8'><title>PDF Output</title></head><body style='font-family: Arial, sans-serif;'><header style='text-align: center; margin-top: 20px;'><h1 style='font-size: 36px; color: #4CAF50;'>The Incredible World of Cats</h1></header><main style='margin: 40px;'><p style='font-size: 18px; line-height: 1.6;'>Cats are truly fascinating creatures...</p></main></body></html>",
  "page_orientation": "landscape",
  "page_size": "Full"
}

{
  "body": {
    "content_type": "application/pdf",
    "filename": "7qMsRsxTz8.pdf",
    "page_orientation": "landscape",
    "page_size": "Full",
    "url": "https://pro-bee-beepro-pdf.s3.amazonaws.com/public/pdf/7qMsRsxTz8.pdf"
  },
  "statusCode": 200
}

Note: The response is a JSON string that will contain the URL of the temporary location of the PDF document. The file is available for 24 hours.

Image

URL: https://api.getbee.io/v1/{collection}/image

Prior to using the image endpoint, ensure you reference the following information.

The HTML is rendered in a fixed window size of 1920x1080 to generate a screenshot, with default viewport widths of 320 pixels for mobile and 1024 pixels for desktop, which may cause cropped previews if the content exceeds these dimensions. A clipping size of 1920x1080 is applied, but it can be customized, and the scale factor adjusts to align the viewport and clipping dimensions. For improved results, using auto height with the size parameter is recommended.

Name

Type

Description

html*

String

A Beefree HTML message.

size

String

Use “size” instead of “width” and “height” when you only know the width and want the height automatically calculated. Required if width and height are not defined.

width

Integer

The image width in pixels. Required if size is not defined.

height

Integer

The image height in pixels. Default applies a proportional value based on the given width, keeping the image aspect ratio. When the value is not proportional to the given width, either will occur: If it’s higher, the proportional value applies, or, if it’s lower, the image is cropped. Required if size is not defined.

file_type*

String

Accepts jpg or png.

Transform HTML to Image

post

Transform HTML and image settings into an image.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection ID or name

Body

file_typestringRequired

Accepts jpg or png

heightintegerOptional

The image height in pixels

htmlstringRequired

A BeeFree HTML message

sizestringOptional

Image size if width and height are not defined

widthintegerOptional

The image width in pixels

Responses

200

The image response as a binary data in PNG format

image/png

post

/v1/{collection}/image

POST /v1/{collection}/image HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 214

{
  "file_type": "png",
  "html": "<!DOCTYPE html><html lang='en'><head><meta charset='utf-8'><title>Simple HTML</title></head><body><h1>Hello World!</h1><p>This is a simple HTML response.</p></body></html>",
  "size": "1000"
}

200

The image response as a binary data in PNG format

�PNG...

Merge

URL: https://api.getbee.io/v1/{collection}/merge

Merge to replace content

post

Replace or update content in the template using a specific path and value.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Responses

200

Successful operation

application/json

400

Invalid request

post

/v1/{collection}/merge

POST /v1/{collection}/merge HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 415

{
  "replace": [
    {
      "path": "$..rows[?(@.metadata.uid=='508824c4-8d45-11ee-84be-aafd6b2aca16')]",
      "value": {
        "columns": [
          {
            "grid-columns": 4,
            "modules": [
              {
                "descriptor": {
                  "computedStyle": {},
                  "image": {},
                  "paragraph": {}
                },
                "type": "mailup-bee-newsletter-modules-paragraph"
              }
            ],
            "style": {
              "background-color": "transparent"
            }
          }
        ],
        "container": {
          "displayCondition": {}
        },
        "content": {},
        "metadata": {
          "uid": "508824c4-8d45-11ee-84be-aafd6b2aca16"
        },
        "type": ""
      }
    }
  ]
}

{
  "html": "text",
  "json": {
    "page": {
      "body": {},
      "rows": [
        {}
      ],
      "template": {},
      "title": "text"
    },
    "comments": {}
  }
}

Merge Rows

URL: https://api.getbee.io/v1/{collection}/merge-rows

Merge Rows

post

The Merge Rows endpoint enables you to integrate custom fonts and resized images into your designs. It saves custom fonts within the template's JSON, ensuring the correct font is displayed. It also handles image resizing, particularly when the image's initial template width is narrower than the saved row's destination template. To use this endpoint, send your template and rows in JSON format. You will receive a response with an updated template. The rows requiring an update are identified by their rowIdentifier values.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection ID or name

Body

rowIdentifierLabelstringOptional

Label for identifying rows, usually GUID

templateobjectRequired

A Beefree template in JSON format

Responses

200

Updated template with merged rows

application/json

post

/v1/{collection}/merge-rows

POST /v1/{collection}/merge-rows HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1749

{
  "rowIdentifierLabel": "guid",
  "rows": [
    {
      "columns": [
        {
          "grid-columns": 12,
          "modules": [
            {
              "descriptor": {
                "computedStyle": {
                  "hideContentOnAmp": false,
                  "hideContentOnDesktop": false,
                  "hideContentOnHtml": false,
                  "hideContentOnMobile": false
                },
                "paragraph": {
                  "computedStyle": {
                    "linkColor": "#7747FF",
                    "paragraphSpacing": "16px"
                  },
                  "html": "<p>Updated paragraph block.</p>",
                  "style": {
                    "color": "#101112",
                    "direction": "ltr",
                    "font-family": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
                    "font-size": "16px",
                    "font-weight": "400",
                    "letter-spacing": "0px",
                    "line-height": "120%",
                    "text-align": "left"
                  }
                },
                "style": {
                  "padding-bottom": "10px",
                  "padding-left": "10px",
                  "padding-right": "10px",
                  "padding-top": "10px"
                }
              },
              "locked": false,
              "type": "mailup-bee-newsletter-modules-paragraph",
              "uuid": "29cd2a3d-fd76-4537-a91b-b8cb9872d8a3"
            }
          ],
          "style": {
            "background-color": "transparent",
            "border-bottom": "0px solid transparent",
            "border-left": "0px solid transparent",
            "border-right": "0px solid transparent",
            "border-top": "0px solid transparent",
            "padding-bottom": "5px",
            "padding-left": "0px",
            "padding-right": "0px",
            "padding-top": "5px"
          },
          "uuid": "56119ad2-574d-4122-8dd1-c1152b5f4879"
        }
      ]
    }
  ],
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#ffffff"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#7747FF",
            "messageBackgroundColor": "transparent",
            "messageWidth": "600px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, Helvetica, sans-serif"
          }
        },
        "webFonts": [
          {
            "fontFamily": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
            "name": "Alegreya",
            "url": "https://fonts.googleapis.com/css2?family=Alegreya:wght@100;200;300;400;500;600;700;800;900"
          },
          {
            "fontFamily": "'Arvo', 'Courier New', Courier, monospace",
            "name": "Arvo",
            "url": "https://fonts.googleapis.com/css2?family=Arvo:wght@100;200;300;400;500;600;700;800;900"
          }
        ]
      }
    },
    "title": ""
  }
}

200

Updated template with merged rows

{
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#ffffff"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#7747FF",
            "messageBackgroundColor": "transparent",
            "messageWidth": "600px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, Helvetica, sans-serif"
          }
        },
        "webFonts": [
          {
            "fontFamily": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
            "name": "Alegreya",
            "url": "https://fonts.googleapis.com/css2?family=Alegreya:wght@100;200;300;400;500;600;700;800;900"
          },
          {
            "fontFamily": "'Arvo', 'Courier New', Courier, monospace",
            "name": "Arvo",
            "url": "https://fonts.googleapis.com/css2?family=Arvo:wght@100;200;300;400;500;600;700;800;900"
          }
        ]
      },
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 12,
              "modules": [
                {
                  "descriptor": {
                    "paragraph": {
                      "html": "<p>Updated paragraph block.</p>",
                      "style": {
                        "color": "#101112",
                        "font-family": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
                        "font-size": "16px"
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      ],
      "warnings": [
        {
          "msg": "No merges were completed for row with identifier 0922fb70-f97e-4ae8-bcfe-0be9fd09a0d5"
        }
      ]
    }
  }
}

When utilizing this feature, it's important to consider adding a handle to the metadata. This handle serves a crucial role in functions such as onDeleteRow and onEditRow. In our provided example, we use a handle named guid. However, users have the flexibility to choose their own handle name according to their preferences and requirements. When selecting a handle name, we recommend you choose something descriptive and meaningful for ease of identification and management within your workflow.

Synced Rows

URL: https://api.getbee.io/v1/{collection}/synced-rows

Get Synced Rows

post

Retrieve a list of synced rows from a template.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection name.

Body

rowIdentifierLabelstringRequired

The label used for identifying the rows added to the metadata key, usually GUID.

Responses

200

A successful response with a list of synced rows.

application/json

400

Invalid input or request parameters.

post

/v1/{collection}/synced-rows

POST /v1/{collection}/synced-rows HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 812

{
  "rowIdentifierLabel": "guid",
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#ffffff"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#7747FF",
            "messageBackgroundColor": "transparent",
            "messageWidth": "600px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, Helvetica, sans-serif"
          }
        }
      },
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 12,
              "modules": [
                {
                  "descriptor": {
                    "paragraph": {
                      "html": "<p>I'm a new paragraph block.</p>",
                      "style": {
                        "color": "#101112",
                        "font-family": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
                        "font-size": "16px"
                      }
                    }
                  }
                }
              ],
              "metadata": {
                "guid": "0922fb70-f97e-4ae8-bcfe-0be9fd09a0d5"
              },
              "synced": true
            }
          ]
        }
      ]
    },
    "webFonts": [
      {
        "fontFamily": "'Alegreya', 'Trebuchet MS', Helvetica, sans-serif",
        "name": "Alegreya",
        "url": "https://fonts.googleapis.com/css2?family=Alegreya:wght@100;200;300;400;500;600;700;800;900"
      }
    ]
  }
}

{
  "syncedRows": [
    {
      "rowIdentifier": "0922fb70-f97e-4ae8-bcfe-0be9fd09a0d5",
      "rowIndex": 0
    }
  ]
}

Index

URL: https://api.getbee.io/v1/{collection}/merge/index

Index Rows

post

Reference an array of metadata objects from a Beefree template in JSON format.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionstringRequired

The collection ID or name

Body

sourceobjectRequired

A Beefree template in JSON format

Responses

200

An array of metadata objects containing row details

application/json

post

/v1/{collection}/merge/index

POST /v1/{collection}/merge/index HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1987

{
  "source": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#FFFFFF"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#FF819C",
            "messageBackgroundColor": "transparent",
            "messageWidth": "675px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Arial, 'Helvetica Neue', Helvetica, sans-serif"
          }
        },
        "type": "mailup-bee-page-properties",
        "webFonts": [
          {
            "fontFamily": "'Montserrat', 'Trebuchet MS', 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', Tahoma, sans-serif",
            "name": "Montserrat",
            "url": "https://fonts.googleapis.com/css?family=Montserrat"
          }
        ]
      },
      "description": "BF-ecommerce-template",
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 6,
              "modules": [
                {
                  "descriptor": {
                    "computedStyle": {
                      "class": "center fixedwidth",
                      "width": 338
                    },
                    "image": {
                      "alt": "Image",
                      "href": "https://beefree.io",
                      "src": "https://d1oco4z2z1fhwp.cloudfront.net/templates/default/113/logo_1.png"
                    },
                    "style": {
                      "padding-bottom": "0px",
                      "padding-left": "15px",
                      "padding-right": "15px",
                      "padding-top": "5px",
                      "width": "100%"
                    }
                  },
                  "locked": false,
                  "type": "mailup-bee-newsletter-modules-image"
                },
                {
                  "descriptor": {
                    "computedStyle": {
                      "align": "center",
                      "hideContentOnMobile": true
                    },
                    "divider": {
                      "style": {
                        "border-top": "0px solid transparent",
                        "height": "20px",
                        "width": "100%"
                      }
                    },
                    "style": {
                      "padding-bottom": "10px",
                      "padding-left": "10px",
                      "padding-right": "10px",
                      "padding-top": "10px"
                    }
                  },
                  "locked": false,
                  "type": "mailup-bee-newsletter-modules-divider"
                }
              ],
              "style": {
                "background-color": "transparent",
                "padding-bottom": "0px",
                "padding-left": "0px",
                "padding-right": "0px",
                "padding-top": "30px"
              }
            }
          ],
          "container": {
            "style": {
              "background-color": "#FF819C",
              "background-image": "none",
              "background-position": "top left",
              "background-repeat": "no-repeat"
            }
          },
          "content": {
            "computedStyle": {
              "hideContentOnDesktop": false,
              "hideContentOnMobile": false,
              "rowColStackOnMobile": true
            },
            "style": {
              "background-color": "transparent",
              "color": "#333",
              "width": "675px"
            }
          },
          "locked": false,
          "metadata": {
            "guid": "test3",
            "name": "demo3"
          },
          "type": "two-columns-empty"
        }
      ],
      "template": {
        "name": "template-base",
        "type": "basic",
        "version": "2.0.0"
      },
      "title": "BF-ecommerce-template"
    }
  }
}

200

An array of metadata objects containing row details

[
  {
    "guid": "test3",
    "name": "demo3"
  }
]

AI Collection

The resources in the AI collection accept your template JSON and use generative AI to return text within a JSON object to you.

Prerequisites

Prior to getting started with the resources in this collection, ensure you have the following:

Superpowers subscription or higher
OpenAI AddOn installed and configured in your Beefree Developer Console
Content Services API key

Note: OpenAI billing costs apply in addition to the Content Services API billing.

Metadata (Preheader and Subject)

v1/ai/metadata

Generate Metadata (Preheader and Subject)

post

The endpoint accepts a JSON template and returns a JSON object with metadata.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Responses

200

A JSON object with metadata (preheader and subject).

application/json

post

/v1/ai/metadata

POST /v1/ai/metadata HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 952

{
  "options": {
    "model": "gpt-3.5-turbo",
    "toneOfVoice": "",
    "instructions": "Try to use a pun.",
    "reportUsage": true,
    "language": ""
  },
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#fff",
            "background-image": "none",
            "background-position": "top left",
            "background-repeat": "no-repeat",
            "background-size": "auto"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#8a3b8f",
            "messageBackgroundColor": "transparent",
            "messageWidth": "650px"
          },
          "style": {
            "color": "#000000",
            "font-family": "Lato, Tahoma, Verdana, Segoe, sans-serif"
          }
        }
      },
      "type": "mailup-bee-page-properties",
      "webFonts": [
        {
          "fontFamily": "'Lato', Tahoma, Verdana, Segoe, sans-serif",
          "name": "Lato",
          "url": "https://fonts.googleapis.com/css?family=Lato"
        }
      ]
    },
    "template": {
      "name": "template-base",
      "type": "basic",
      "version": "2.0.0"
    },
    "title": "",
    "description": "",
    "rows": [
      {
        "columns": [
          {
            "grid-columns": 12,
            "modules": [
              {
                "descriptor": {
                  "computedStyle": {
                    "align": "center"
                  },
                  "style": {
                    "padding-top": "10px",
                    "padding-bottom": "5px"
                  }
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

200

A JSON object with metadata (preheader and subject).

{
  "preheader": "Ready to Bee a part of our user research project? Schedule your interview now!",
  "subject": "BEE Pro: Let's Bee-gin! Join our user research project 🐝",
  "usage": {
    "prompt_tokens": 424,
    "completion_tokens": 48,
    "total_tokens": 472,
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

SMS

v1/ai/sms

Generate SMS from Template

post

This endpoint accepts a JSON template and options to generate a custom SMS.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Responses

200

Successful response with SMS.

application/json

post

/v1/ai/sms

POST /v1/ai/sms HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 335

{
  "options": {
    "model": "gpt-3.5-turbo",
    "toneOfVoice": "text",
    "length": "detailed",
    "instructions": "text",
    "reportUsage": true,
    "language": "it-IT"
  },
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#fff",
            "background-image": "none",
            "background-position": "top left",
            "background-repeat": "no-repeat",
            "background-size": "auto"
          }
        }
      }
    }
  }
}

200

Successful response with SMS.

{
  "sms": "Ciao! Ti interessa partecipare a un progetto di ricerca utente con noi? Sarà una videochiamata di 30-45 minuti.",
  "usage": {
    "prompt_tokens": 475,
    "completion_tokens": 87,
    "total_tokens": 562
  }
}

Summary

v1/ai/summary

Generate Summary from Template

post

This endpoint accepts a JSON template and options to generate a concise summary.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Responses

200

Successful response with summary.

application/json

post

/v1/ai/summary

POST /v1/ai/summary HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 334

{
  "options": {
    "model": "gpt-3.5-turbo",
    "toneOfVoice": "text",
    "length": "concise",
    "instructions": "text",
    "reportUsage": true,
    "language": "it-IT"
  },
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "background-color": "#fff",
            "background-image": "none",
            "background-position": "top left",
            "background-repeat": "no-repeat",
            "background-size": "auto"
          }
        }
      }
    }
  }
}

200

Successful response with summary.

{
  "summary": "Vuoi partecipare a un progetto di ricerca utente con BEE Pro? Rispondi a Dalila per prenotare un colloquio video.",
  "usage": {
    "prompt_tokens": 425,
    "completion_tokens": 39,
    "total_tokens": 464
  }
}

Conversion Collection

The Conversion Collection provides you with endpoints that enable you to convert templates from one format to another. With the Email to Page endpoint, you can easily convert your email JSON templates into page JSON. The Page to Email endpoint lets you turn your page JSON templates into email-ready JSON, with the option to disable the HTML sanitizer if needed.

Email to Page Conversion: Important Behaviors

The Email to Page endpoint converts a JSON template created for email into a JSON template optimized for web pages. During this conversion, the following adjustments are applied:

Remove AMP Carousel Any AMP carousels included in the email template are removed, as these are not supported in the page format.
Expand Content Area Width The content width is expanded to 900px to fit the web page format, removing the width constraints typically applied to emails.
Target Attributes Target attributes will not be processed. Remove all link target attributes or set them to "Open a new page." Links will not be modified during the conversion.
Remove Subject and Preheader Email-specific metadata, such as the subject line and preheader text, is removed since these elements are not relevant in the page format.
Retain Comments and Secondary Language Comments and secondary language data in the email template are preserved in the conversion process.

Convert Email JSON to Page JSON

post

Converts an email JSON template to a page JSON template, ensuring compatibility by converting or removing unsupported blocks.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Responses

200

Successful conversion to page JSON template

application/json

post

/v1/conversion/email-to-page

POST /v1/conversion/email-to-page HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 858

{
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "backgroundColor": "#FFFFFF"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#0068A5",
            "messageBackgroundColor": "transparent",
            "messageWidth": "500px"
          },
          "style": {
            "color": "#000000",
            "fontFamily": "Arial, Helvetica, sans-serif"
          }
        }
      },
      "description": "Empty template for BEE",
      "rows": [
        {
          "columns": [
            {
              "gridColumns": 12,
              "modules": [
                {
                  "type": "text",
                  "descriptor": {
                    "computedStyle": {
                      "hideContentOnAmp": true,
                      "hideContentOnHtml": true,
                      "hideContentOnDesktop": true,
                      "hideContentOnMobile": true
                    },
                    "paragraph": {
                      "html": "<p>I'm a new paragraph block.</p>",
                      "style": {
                        "color": "#000000",
                        "fontSize": "14px",
                        "fontFamily": "inherit"
                      }
                    }
                  },
                  "uuid": "c8ecedba-4891-46fa-9aec-1f4ef3276914",
                  "locked": false
                }
              ],
              "style": {
                "backgroundColor": "transparent",
                "paddingTop": "5px"
              }
            }
          ]
        }
      ]
    },
    "template": {
      "name": "template-base",
      "type": "basic",
      "version": "2.0.0"
    },
    "title": "Empty Template"
  }
}

200

Successful conversion to page JSON template

{
  "page": {
    "body": {
      "container": {
        "style": {
          "backgroundColor": "#FFFFFF"
        }
      },
      "content": {
        "computedStyle": {
          "linkColor": "#0068A5",
          "messageBackgroundColor": "transparent",
          "messageWidth": "900px"
        },
        "style": {
          "color": "#000000",
          "fontFamily": "Arial, Helvetica, sans-serif"
        }
      }
    },
    "description": "Empty template for BEE",
    "rows": [
      {
        "columns": [
          {
            "gridColumns": 12,
            "modules": [
              {
                "type": "mailup-bee-newsletter-modules-paragraph",
                "descriptor": {
                  "computedStyle": {
                    "hideContentOnAmp": true,
                    "hideContentOnHtml": true,
                    "hideContentOnDesktop": true,
                    "hideContentOnMobile": true
                  },
                  "paragraph": {
                    "html": "<p>I'm a new paragraph block.</p>",
                    "style": {
                      "color": "#000000",
                      "fontSize": "14px",
                      "fontFamily": "inherit"
                    }
                  }
                },
                "uuid": "c8ecedba-4891-46fa-9aec-1f4ef3276914",
                "locked": false
              }
            ]
          }
        ]
      }
    ]
  }
}

Page to Email Conversion: Important Behaviors

The Page to Email endpoint transforms a JSON template designed for a web page into a JSON template optimized for email. During this conversion process, the following adjustments are made:

Remove Video Row Backgrounds Video backgrounds applied to page rows are removed because email formats do not support video backgrounds.
Replace Embedded Videos with Thumbnails Embedded videos are replaced with thumbnail images. This ensures recipients can preview the content visually without the compatibility issues of embedded videos. Note: Hosted videos will not be converted.
Remove Form Blocks Any form blocks present in the page template are removed.
Adjust Design Content Area Width If the page width exceeds the maximum width supported by the email builder (900px), it is resized to fit within email constraints.
Update Link Target Attributes Target attributes will not be processed. Remove all link target attributes. Links will not be modified during the conversion.
Sanitize Code The endpoint sanitizes the code to ensure compatibility with email standards. When the sanitizer is disabled, the payload looks like this:
```
{
  "disableHtmlSanitizer": true,
  "template": { "page": ... }
}
```
Handle Multi-Column Layouts The email builder supports up to 12 columns, which is compatible with the page builder's column configurations.

Convert Page JSON to Email JSON

post

Converts a page JSON template to an email JSON template, ensuring compatibility by converting or removing unsupported blocks. By default, the conversion sanitizes HTML modules, which can be disabled by setting a specific parameter.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

disableHtmlSanitizerbooleanOptional

Option to disable HTML sanitizer

Example: true

Responses

200

Successful conversion to email JSON template

application/json

post

/v1/conversion/page-to-email

POST /v1/conversion/page-to-email HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 853

{
  "disableHtmlSanitizer": true,
  "template": {
    "page": {
      "body": {
        "container": {
          "style": {
            "backgroundColor": "#FFFFFF"
          }
        },
        "content": {
          "computedStyle": {
            "linkColor": "#0068A5",
            "messageBackgroundColor": "transparent",
            "messageWidth": "500px"
          },
          "style": {
            "color": "#000000",
            "fontFamily": "Arial, Helvetica, sans-serif"
          }
        }
      },
      "description": "Empty template for BEE",
      "rows": [
        {
          "columns": [
            {
              "gridColumns": 12,
              "modules": [
                {
                  "type": "text",
                  "descriptor": {
                    "computedStyle": {
                      "hideContentOnAmp": true,
                      "hideContentOnHtml": true,
                      "hideContentOnDesktop": true,
                      "hideContentOnMobile": true
                    },
                    "html": {
                      "html": "<div class=\"our-class\"><script>console.log(\"ok\");</script>test 1</div>"
                    }
                  },
                  "uuid": "f6c6a079-dd90-4589-8855-93dfdf74461d",
                  "locked": false
                }
              ],
              "style": {
                "backgroundColor": "transparent",
                "paddingTop": "5px"
              }
            }
          ]
        }
      ]
    },
    "template": {
      "name": "template-base",
      "type": "basic",
      "version": "2.0.0"
    },
    "title": "Empty Template"
  }
}

200

Successful conversion to email JSON template

{
  "page": {
    "body": {
      "container": {
        "style": {
          "backgroundColor": "#FFFFFF"
        }
      },
      "content": {
        "computedStyle": {
          "linkColor": "#0068A5",
          "messageBackgroundColor": "transparent",
          "messageWidth": "500px"
        },
        "style": {
          "color": "#000000",
          "fontFamily": "Arial, Helvetica, sans-serif"
        }
      }
    },
    "description": "Empty template for BEE",
    "rows": [
      {
        "columns": [
          {
            "gridColumns": 12,
            "modules": [
              {
                "type": "mailup-bee-newsletter-modules-html",
                "descriptor": {
                  "computedStyle": {
                    "hideContentOnAmp": true,
                    "hideContentOnHtml": true,
                    "hideContentOnDesktop": true,
                    "hideContentOnMobile": true
                  },
                  "html": {
                    "html": "<div class=\"our-class\"><script>console.log(\"ok\");</script>test 1</div>"
                  }
                },
                "uuid": "f6c6a079-dd90-4589-8855-93dfdf74461d",
                "locked": false
              }
            ]
          }
        ]
      }
    ]
  }
}

PreviousCSAPI Overview NextBrand Style Management

Last updated 1 year ago

Was this helpful?

hashtagAPI Key

hashtagRate Limits

hashtagAPI Root

hashtagCollections

hashtagExample URLs

hashtagResources

hashtagHTML

hashtagTransform JSON Template to HTML

hashtagPlain Text

hashtagGenerate Plain Text

hashtagPDF

hashtagGenerate PDF

hashtagImage

hashtagTransform HTML to Image

hashtagMerge

hashtagMerge to replace content

hashtagMerge Rows

hashtagMerge Rows

hashtagSynced Rows

hashtagGet Synced Rows

hashtagIndex

hashtagIndex Rows

hashtagAI Collection

hashtagPrerequisites

hashtagMetadata (Preheader and Subject)

hashtagGenerate Metadata (Preheader and Subject)

hashtagSMS

hashtagGenerate SMS from Template

hashtagSummary

hashtagGenerate Summary from Template

hashtagConversion Collection

hashtagEmail to Page Conversion: Important Behaviors

hashtagConvert Email JSON to Page JSON

hashtagPage to Email Conversion: Important Behaviors

hashtagConvert Page JSON to Email JSON

API Key

Rate Limits

API Root

Collections

Example URLs

Resources

HTML

Transform JSON Template to HTML

Plain Text

Generate Plain Text

PDF

Generate PDF

Image

Transform HTML to Image

Merge

Merge to replace content

Merge Rows

Merge Rows

Synced Rows

Get Synced Rows

Index

Index Rows

AI Collection

Prerequisites

Metadata (Preheader and Subject)

Generate Metadata (Preheader and Subject)

SMS

Generate SMS from Template

Summary

Generate Summary from Template

Conversion Collection

Email to Page Conversion: Important Behaviors

Convert Email JSON to Page JSON

Page to Email Conversion: Important Behaviors

Convert Page JSON to Email JSON