> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Email Template
> This API searches the email templates created in your MoEngage account.
**Note**
We are introducing mandatory pagination, effective November 15, 2025, all calls to this API must include the following two parameters:
* `page`: The page number of the results you wish to fetch.
* `entries`: The number of templates to return per page, with a maximum value of 15.
Please update all integrations to include these parameters. API requests submitted without them after the effective date will result in an error and fail to execute.
#### Rate Limit
The rate limit is 100 Requests Per Minute.
## OpenAPI
````yaml /api/email-templates-2/email-templates-2.yaml post /custom-templates/email/search
openapi: 3.1.0
info:
title: Email Templates API V2
version: v1.0
description: >
The Create Email Template API can be used to create an email template in
MoEngage. This API helps you upload templates created outside the MoEngage
ecosystem to MoEngage and use them for campaign creation. The uploaded
templates can be edited in the Froala editor (custom HTML editor) on the
MoEngage Dashboard.
**Note**
Templates created using this API cannot be used in the Drag and Drop Editor
in the MoEngage Dashboard. They are supported only for the Custom HTML
Editor (Froala Editor).
servers:
- url: https://api-{dc}.moengage.com/v1.0
description: MoEngage API Server
variables:
dc:
default: '01'
description: >-
The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center
(DC). MoEngage hosts each customer in a different DC. You can find
your DC number and replace the value of ‘dc’ in the URL by referring
to the DC and API endpoint mapping
[here](/api/introduction#data-centers). Your MoEngage Data Center (DC)
can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
tags:
- name: Email Templates
description: Manage custom email templates.
paths:
/custom-templates/email/search:
post:
tags:
- Email Templates
summary: Search Email Template
description: |
This API searches the email templates created in your MoEngage account.
operationId: searchEmailTemplate
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
**Note:**
- `page` and `entries` are mandatory effective November 15,
2025. All other fields are optional.
- You can send empty filters to fetch all the email templates.
- You can send only `template_ids` if you want specific older
versions of the email template. In other cases, you will receive
the latest version of the template.
- By default, the `is_default_template_of_group` flag is set to
"true" for the default (parent) template and "false" for child
templates.
required:
- page
- entries
properties:
page:
type: integer
description: >-
This field contains the index of the pages to be returned in
the search result.
entries:
type: integer
description: >-
This field contains the number of entries per page in the
search result. Maximum value is 15.
maximum: 15
template_name:
type: string
description: >-
This field indicates the name of the template. When this
value is specified, the template that matches the name
specified in this field will be returned.
template_source:
type: array
items:
type: string
description: >-
This field indicates the template source that created the
template. For example ["API", "MOENGAGE"]. When specified,
the templates whose source matches that specified in this
list will be returned.
template_version:
type: string
description: >-
This field indicates the template version. When specified,
the template whose template version matches that specified
in this field will be returned.
template_id:
type: string
description: >-
This field indicates the template id. When specified, the
template whose template id matches that specified in this
field will be returned.
template_type:
type: array
items:
type: string
description: >
This field indicates whether the template is a custom one or
a pre-built one.
Allowed values: CUSTOM, PRE_BUILT.
When specified, the templates whose template type matches
that specified in this list will be returned.
created_by:
type: array
items:
type: string
description: >
This field indicates the user who created the template. When
specified, the templates for which the created_by user
information matches that specified in this list will be
returned.
Example: ["user1@moengage.com", "user2@moengage.com"]
updated_by:
type: array
items:
type: string
description: >
This field indicates the user who updated the template. When
specified, the templates for which the updated_by user
information matches that specified in this list will be
returned.
Example: ["user1@moengage.com", "user2@moengage.com"]
sort_params:
type: array
items:
type: object
description: >
This field indicates the sorting parameters for the search
result and the sort order.
Example: "sort_params":[{"template_name":
"ASCENDING","last_modified_date":
"ASCENDING","last_modified_by": "ASCENDING"}]
external_template_ids:
type: array
items:
type: object
properties:
external_template_id:
type: string
version:
type: integer
description: >
This field indicates the list of the template ids and their
versions that must be fetched. When this value is specified,
the template that matches the id and version specified in
this field will be returned.
group_id:
type: string
description: >
This field indicates the group ID of the parent template.
Pass the Group ID of the parent (default) template of the
group to fetch all templates associated with that group.
The "external_template_id" generated for the parent template
acts as its group ID.
is_grouped_response:
type: boolean
description: >
If the value is "true", this API fetches only the default
template data, including additional fields such as unique
locale count, unique variations, total templates in the
group, and all individual templates that are not part of any
group.
If the value is "false", this API will fetch all individual
templates and their template data.
is_count_required:
type: boolean
description: >-
If the value is "true", this API fetches total templates of
the same request to support pagination on the UI.
responses:
'200':
description: >-
This response is returned when the request is processed
successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: >
This field contains the list of email templates that
satisfy the search criteria.
For information about the template, refer to Basic Details
and Meta Info.
items:
type: object
properties:
external_template_id:
type: string
version:
type: integer
meta_info:
$ref: '#/components/schemas/MetaInfo'
basic_details:
$ref: '#/components/schemas/BasicDetails'
created_by:
type: string
created_at:
type: string
updated_by:
type: string
updated_at:
type: string
error:
type: object
description: This field contains the reason for the request's failure.
properties:
code:
type: string
description: >-
This field contains the error code that provides a
brief explanation of the error and is a String.
message:
type: string
description: >-
This field describes why the request has failed and is
a String.
details:
type: array
description: This is a List of the error details objects.
items:
type: object
request_id:
type: string
description: >-
This field contains the unique id pertaining to the
request.
examples:
success:
value:
data:
- external_template_id: '{{external_template_id}}'
version: 2
basic_details:
email_content: >-
Sample
WebpageWelcome to My Sample
Webpage 1
This is a small example of an HTML
webpage.
Below is an unordered
list:
Here's an image:
Visit our website for more
information.
subject: Hi, Test subject 1
attachments: []
thumbnail_url: >-
https://img.freepik.com/free-vector/bright-yellow-sunflower-design-decorations_1308-130330.jpg
sender_name: test sender 1
meta_info:
template_id: '{{template_id}}'
template_name: test_template_1
template_version: '0'
created_by: user1@moengage.com
'400':
description: >-
This response is returned when the required parameters are missing
from the request, when the provided parameters are invalid, or when
a template already exists with the same version, name, or ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_field:
value:
error:
code: 400 Bad Request
message: Invalid Field Value
details:
- code: InvalidValue
target:
- template_name
- created_by
message: Some of the field values are invalid
request_id: '{{request_id}}'
'401':
description: >-
This response is returned when the authorization parameters are
missing in the HTTP Auth Header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
auth_fail:
value:
error:
code: 401 Unauthorized
message: Authentication required
details:
- code: InvalidValue
target: APP_ID
message: Invalid APP_ID is provided.
request_id: '{{request_id}}'
'429':
description: >-
This response is returned when the number of requests per minute has
exceeded the rate limit.
content:
application/json:
schema:
type: object
properties:
response_id:
type: string
type:
type: string
error:
type: object
properties:
code:
type: string
message:
type: string
examples:
rate_limit:
value:
response_id: '{{response_id}}'
type: custom_template
error:
code: Too Many Requests
message: 'API rate limit breached. Current limit: n/m mins'
'500':
description: >-
This response is returned when the system runs into an unexpected
error.
content:
application/json:
schema:
type: object
properties:
title:
type: string
message:
type: string
examples:
server_error:
value:
title: Internal Server Error
message: >-
An unexpected error was encountered while processing this
request. Please contact MoEngage Team
components:
schemas:
MetaInfo:
type: object
description: >
This field contains information about the template being created, such
as the name, version, and ID of the template and the creator's details.
required:
- template_id
- template_name
- template_version
- created_by
properties:
template_id:
type: string
description: >-
This field contains the ID for the template and is unique. This ID
should be generated by you and will be used for updating or
retrieving the template using the template APIs.
template_name:
type: string
description: >-
This field contains the name of the template. This value should be
generated by you and would be used for identifying the template.
template_version:
type: string
description: >-
This field contains the version of the template and is unique. This
value should be generated by you and would be used for tracking the
template's version.
created_by:
type: string
description: >-
This field contains details about who created the template. This
value should be generated by you. For example, you can pass the
email id of the user creating the template here.
locale:
type: string
description: >
This field contains the locale to be associated with the template.
These are the locales available in the MoEngage Dashboard at
**Settings > Advanced settings > Locales**.
variation:
type: integer
description: >-
This field contains the variation of the template. You can add a
maximum of five variations to each template.
group_id:
type: string
description: >
This field contains the group ID of the template.
* Parent template: A parent template is the "default" template with
which you can associate child templates. You need not pass a Group
ID for a parent template. The "external_template_id" generated for
the parent template acts as its group ID.
* Child template: Pass the Group ID of the parent (default) template
with which you want to associate the child template.
BasicDetails:
type: object
description: >
This field contains the email content. This is where you define the
email template being created.
required:
- email_content
- subject
- thumbnail_url
- sender_name
properties:
email_content:
type: string
description: This field contains the title of the message.
subject:
type: string
description: |
This field contains the subject of the email campaign.
**Example**: "End of Season Sale!"
attachments:
type: array
description: >
This field contains the attachments to be included in the email.
**Note**:
* Only URLs can be added as part of Email attachments.
* A maximum of ten attachments are allowed.
* The URL should start with https and end with a valid extension.
The following extensions are not allowed: .dmg, .exe, .xls, .ddl,
.class, .obj, .int, .gnt, .o, .so, .lbr, and .net
* Individual attachments should be less than 6 MB, and the total
size of the attachments should be less than 20 MB.
items:
type: string
format: uri
example: https://app-cdn.moengage.com/assets/LogoThumbnail.jpg
thumbnail_url:
type: string
description: >-
This field contains the image URL used to generate a preview in the
Imported API Templates section on the MoEngage dashboard.
sender_name:
type: string
description: >
This field contains the name that is displayed in the inboxes of
your recipients. Sender names are one of the first things people see
when you send them an email.
**Example**: "sender_name": "Your Brand Name"
preview_text:
type: string
description: >
This field contains the preview text, the text that appears below
the subject line in the inbox.
Example: "preview_text": "Let Your Summer Look Shine"
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
This field contains the error code that provides a brief
explanation of the error and is a String. For example, 400 - Bad
Request, 401- Authentication required, and so on.
message:
type: string
description: This field describes why the request has failed and is a String.
details:
type: array
description: This is a List of the error details objects.
items:
type: object
properties:
code:
type: string
description: Descriptive Error Code
target:
type: string
description: >-
Denotes the field causing the issue or a brief description
of the error message in some cases
message:
type: string
description: Descriptive Error Message
request_id:
type: string
description: This field contains the unique id pertaining to the request.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Authentication is done via Basic Auth. This requires a base64-encoded
string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App
ID). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: Use your API Key, which you can find within the
**Campaign report/Business events/Custom templates/Catalog API/Inform
Report** tile.
For more information on authentication and getting your credentials,
refer
[here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
````