Jump to

• Request
• Response

Update email templates

put

/ccadmin/v1/email/types/{emailTypeId}/templates

Uploads custom Freemarker templates for the subject and body of the email type for a specific site, along with associated locale-specific resource files. These allow you to apply site-specific custom email formatting for the given email type.

The custom email templates and locale resources must first be uploaded in zip form using the file's admin endpoints (startFileUpload and doFileSegmentUpload).

These file endpoints and the updateEmailTemplate endpoint support the site context specified using the X-CCSite request header, which should specify the applicable site. If the site is omitted, the default site is assumed.

The email type to be updated is identified by the {emailTypeId} path parameter. The emailTypeId parameter must correspond to the ID of an existing email type; for example, the emailTypeId for the Abandon Order email type is abandon_order_v1. The updateEmailTemplate endpoint takes a JSON request body where the location of the uploaded zip file is specified via a filename field.

Request

Supported Media Types

• application/json

Path Parameters

• emailTypeId: string
  The ID of the email type.

Body ()

Root Schema : updateEmailTemplates_request

Type: object

Show Source

• filename: string
  Path to previously uploaded zip file containing email templates to apply for the specified email type.

{
    "properties":{
        "filename":{
            "description":"Path to previously uploaded zip file containing email templates to apply for the specified email type.",
            "type":"string"
        }
    },
    "required":[
        "filename"
    ],
    "example":{
        "filename":"notifications/uploads/abandoned_order_v1.zip"
    }
}

Example:

{
    "filename":"notifications/uploads/abandoned_order_v1.zip"
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Returned when the operation completes without error.
Note: The success property in the response indicates whether the update was successful or not.
If successful, it will return the success property as true and no further action is needed.
If the success property is false, the error array property in the response shows any errors.
A table of possible errors is listed below.

Error Array Descriptions
Uploaded zip file does not contain subject.ftl file
The uploaded zip file does not contain html_body.ftl or text_body.ftl
Strings.xlf for the default locale must be present under locales/'locale'
The contents of the Freemarker templates (subject.ftl, html_body.ftl or text_body.ftl) are invalid.
Duplicate resources (xx_yy and xx-yy folders under locales)

Note:If any errors occur during validation checks, the uploaded template will not be applied.

Body ()

Root Schema : updateEmailTemplates_200_response

Type: object

Show Source

• displayName(optional): string
  The display name for the email type
• errors(optional): array errors
  Errors reported for the update.
• success(optional): boolean
  true - if update was successful, false - if update was unsuccessful
• warnings(optional): array warnings
  Warnings reported for the update.

{
    "properties":{
        "success":{
            "description":"true - if update was successful, false - if update was unsuccessful",
            "type":"boolean"
        },
        "displayName":{
            "description":"The display name for the email type",
            "type":"string"
        },
        "warnings":{
            "description":"Warnings reported for the update.",
            "type":"array",
            "items":{
                "type":"string"
            }
        },
        "errors":{
            "description":"Errors reported for the update.",
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : errors

Type: array

Errors reported for the update.

Show Source

• Array of: string

{
    "description":"Errors reported for the update.",
    "type":"array",
    "items":{
        "type":"string"
    }
}

Nested Schema : warnings

Type: array

Warnings reported for the update.

Show Source

• Array of: string

{
    "description":"Warnings reported for the update.",
    "type":"array",
    "items":{
        "type":"string"
    }
}

Example Response (application/json)

{
    "success":true,
    "displayName":"Abandoned Cart",
    "warnings":[
        "Locale 'sh' referenced in 'locales/sh/Strings.xlf' is not a supported locale. This folder and its contents will not be uploaded."
    ],
    "links":[
        {
            "rel":"self",
            "href":"http://admin.example.com/ccadminui/v1/email/types/abandoned_order_v1/templates"
        }
    ],
    "errors":[
    ]
}

400 Response

Returned if the filename parameter is empty.

Body ()

Root Schema : updateEmailTemplates_400_response

Type: object

Show Source

• errorCode(optional): string
  950031
• message(optional): string
  Filename is required for update email templates.
• status(optional): string
  400

{
    "properties":{
        "errorCode":{
            "description":"950031",
            "type":"string"
        },
        "message":{
            "description":"Filename is required for update email templates.",
            "type":"string"
        },
        "status":{
            "description":"400",
            "type":"string"
        }
    }
}

404 Response

Returned if the email type does not exist.

Body ()

Root Schema : updateEmailTemplates_404_response

Type: object

Show Source

• errorCode(optional): string
  00000000
• message(optional): string
  Email type nonesuch does not exist.
• status(optional): string
  400

{
    "properties":{
        "errorCode":{
            "description":"00000000",
            "type":"string"
        },
        "message":{
            "description":"Email type nonesuch does not exist.",
            "type":"string"
        },
        "status":{
            "description":"400",
            "type":"string"
        }
    }
}

Default Response

The following internal error codes are thrown by this API when the request fails in Commerce:

Error Code	Description	Possible Fix
950031	Property 'filename' must exist in the request body.	Ensure you have specified a filename.
950046	Cannot update OCCS Email Notification Type.	Specify another notification type.
950047	Notification Type ID has not been specified.	Specify a valid 'emailTypeId'.
950029	Read-only email type.	Specify a valid 'emailTypeId'.
950030	Internal server error.	See returned error messages for further information.

The error response:

Body ()

Root Schema : errorModel

Type: object

Show Source

• devMessage(optional): string
  An optional non-localized message containing technical information for developers
• errorCode(optional): string
  The numerical code identifying the error
• errors(optional): array errors
  An optional list of errors if multiple errors were encountered
• message(optional): string
  The localized message describing the error
• moreInfo(optional): string
  An optional non-localized message with more information
• o:errorPath(optional): string
  An optional machine readable description of where the error occurred
• status(optional): string
  The HTTP status code
• type(optional): string
  The URI to the HTTP state code definition

{
    "type":"object",
    "properties":{
        "errorCode":{
            "description":"The numerical code identifying the error",
            "type":"string"
        },
        "message":{
            "description":"The localized message describing the error",
            "type":"string"
        },
        "type":{
            "description":"The URI to the HTTP state code definition",
            "type":"string"
        },
        "devMessage":{
            "description":"An optional non-localized message containing technical information for developers",
            "type":"string"
        },
        "moreInfo":{
            "description":"An optional non-localized message with more information",
            "type":"string"
        },
        "o:errorPath":{
            "description":"An optional machine readable description of where the error occurred",
            "type":"string"
        },
        "errors":{
            "description":"An optional list of errors if multiple errors were encountered",
            "type":"array",
            "items":{
                "type":"object",
                "properties":{
                    "errorCode":{
                        "description":"The numerical code identifying the error",
                        "type":"string"
                    },
                    "message":{
                        "description":"The localized message describing the error",
                        "type":"string"
                    },
                    "devMessage":{
                        "description":"An optional non-localized message containing technical information for developers",
                        "type":"string"
                    },
                    "moreInfo":{
                        "description":"An optional non-localized message with more information",
                        "type":"string"
                    },
                    "o:errorPath":{
                        "description":"An optional machine readable description of where the error occurred",
                        "type":"string"
                    },
                    "status":{
                        "description":"The HTTP status code",
                        "type":"string"
                    }
                }
            }
        },
        "status":{
            "description":"The HTTP status code",
            "type":"string"
        }
    }
}

Nested Schema : errors

Type: array

An optional list of errors if multiple errors were encountered

Show Source

• Array of: object items

{
    "description":"An optional list of errors if multiple errors were encountered",
    "type":"array",
    "items":{
        "type":"object",
        "properties":{
            "errorCode":{
                "description":"The numerical code identifying the error",
                "type":"string"
            },
            "message":{
                "description":"The localized message describing the error",
                "type":"string"
            },
            "devMessage":{
                "description":"An optional non-localized message containing technical information for developers",
                "type":"string"
            },
            "moreInfo":{
                "description":"An optional non-localized message with more information",
                "type":"string"
            },
            "o:errorPath":{
                "description":"An optional machine readable description of where the error occurred",
                "type":"string"
            },
            "status":{
                "description":"The HTTP status code",
                "type":"string"
            }
        }
    }
}

Nested Schema : items

Type: object

Show Source

• devMessage(optional): string
  An optional non-localized message containing technical information for developers
• errorCode(optional): string
  The numerical code identifying the error
• message(optional): string
  The localized message describing the error
• moreInfo(optional): string
  An optional non-localized message with more information
• o:errorPath(optional): string
  An optional machine readable description of where the error occurred
• status(optional): string
  The HTTP status code

{
    "type":"object",
    "properties":{
        "errorCode":{
            "description":"The numerical code identifying the error",
            "type":"string"
        },
        "message":{
            "description":"The localized message describing the error",
            "type":"string"
        },
        "devMessage":{
            "description":"An optional non-localized message containing technical information for developers",
            "type":"string"
        },
        "moreInfo":{
            "description":"An optional non-localized message with more information",
            "type":"string"
        },
        "o:errorPath":{
            "description":"An optional machine readable description of where the error occurred",
            "type":"string"
        },
        "status":{
            "description":"The HTTP status code",
            "type":"string"
        }
    }
}

Back to Top