Custom integration using an API | Topol PRO documentation

This guide will walk you through how to retrieve templates using the Topol PRO API.

Setting Up Authorization

To interact with the API, you need to set the Authorization header in your requests. Here's how to get started:

Generate an API Key:
- Go to your Topol account setting and navigate to API Tokens: https://app.topol.io/settings/api-tokens
- Select Create API Token to generate your key.

Set the Authorization Header:

Once you have your API key, include it in your requests as follows:

{
  "accept": "application/json",
  "Authorization": "Bearer <api-key>"
}

Listing Templates

To list your templates, send a GET request to the following API endpoint:

URL: https://app.topol.io/api/templates

Method: GET

Request:

You can use the following parameters:

per_page (integer) - number of templates per page (default: 25, min: 1

current_page (integer) - page number (default: 1, min: 1)

sort_by (string) - possible values: id, created_at, updated_at, name, status, template_folder_id
sort_by_direction (string) - possible values: asc, desc
search (string) - search for templates by name
filter (nullable|array) - filters the templates based on specific criteria, such as template_folder_id or status. The filter should be an array containing a single column and value pair. For example, to filter templates by folder ID, you would use the following structure:

filter: {
   "column": "template_folder_id",
   "value": 1
}

Response

If the request is successful, the server will return a JSON response containing the template data.

Successful Response:

{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "template_folder_id": null,
      "name": "Template One",
      "status": null,
      "updated_at": "2023-01-01T00:00:00.000000Z",
      "created_at": "2023-01-01T00:00:00.000000Z",
      "img_thumb_url": "https://example.com/screenshot.png",
      "team_id": 42556
    },
    {
      "id": 2,
      "user_id": 1,
      "template_folder_id": null,
      "name": "Template Two",
      "status": null,
      "updated_at": "2023-01-01T00:00:00.000000Z",
      "created_at": "2023-01-01T00:00:00.000000Z",
      "img_thumb_url": “https://example.com/screenshot.png”,
      "team_id": team id
    }
  ],
  "total_records": 2,
  "current_page": 1,
  "per_page": 25,
  "next_page": null,
  "prev_page": null,
  "last_page": 1
}

This response contains an array of templates (data), along with pagination information (total_records, current_page, per_page, etc.).

Get Template

To retrieve a specific template by its ID, send a GET request to the following endpoint, replacing <template_id> with the actual template ID:

URL: https://app.topol.io/api/templates/<template_id>

Method: GET

Response

If the request is successful, the server will return a JSON response containing the template data.

Successful Response:

{
  "data": {
    "id": 1,
    "name": "Template 1",
    "screenshot_url": "https://example.com/screenshot.png",
    "definition": {
      /* JSON definition of the template */
    },
    "html": "<html>Your template HTML content here</html>"
  }
}

Error handling

If the request fails, the API will return an error response with an appropriate status code and message.

Error Response Example:

{
  "message": "Error message"
}

This message will help you diagnose issues with your request, such as invalid parameters or authentication problems.

Conclusion

By using the Topol PRO Templates API, you can easily manage and retrieve your email templates programmatically. Whether you're listing multiple templates with specific filters or fetching a single template by ID, the API provides a flexible and powerful way to interact with your email assets. If you encounter any issues or have further questions, feel free to reach out for support.