Templates

Last updated 4 months ago

A "Template" is the content of the emails that are sent to targets. They can be imported from an existing email, or created from scratch.

Additionally, templates can contain tracking images so that gophish knows when the user opens the email.

Templates have the following structure:

{
id : int64
name : string
subject : string
text : string
html : string
modified_date : string(datetime)
attachments : list(attachment)
}

Templates support sending attachments. Attachments have the following structure:

content: string
type : string
name : string

Note: The content field in an attachment is expected to be base64 encoded.

get
Get Templates

https://localhost:3333
/api/templates
Returns a list of templates.
Request
Response
Headers
Authorization
required
string
A valid API key
200: OK
[
{
"id" : 1,
"name" : "Password Reset Template",
"subject" : "{{.FirstName}}, please reset your password.",
"text" : "Please reset your password here: {{.URL}}",
"html" : "<html><head></head><body>Please reset your password <a href\"{{.URL}}\">here</a></body></html>",
"modified_date" : "2016-11-21T18:30:11.1477736-06:00",
"attachments" : [],
}
]

get
Get Template

https://localhost:3333
/api/templates/:id
Returns a template with the provided ID. Returns a 404: Not Found error if the specified template doesn't exist.
Request
Response
Path Parameters
id
required
integer
The template ID
Headers
Authorization
required
string
A valid API key
200: OK
{
"id" : 1,
"name" : "Password Reset Template",
"subject" : "{{.FirstName}}, please reset your password.",
"text" : "Please reset your password here: {{.URL}}",
"html" : "<html><head></head><body>Please reset your password <a href\"{{.URL}}\">here</a></body></html>",
"modified_date" : "2016-11-21T18:30:11.1477736-06:00",
"attachments" : [],
}
404: Not Found
{
"message": "Template not found",
"success": false,
"data": null
}

post
Create Template

https://localhost:3333
/api/templates
Creates a new template from the provided JSON request body.
Request
Response
Headers
Authorization
required
string
A valid API key
Body Parameters
Payload
required
object
The request body should be a JSON representation of a template. See the schema at the top of this page for the template format.
201: Created
{
"id" : 1,
"name" : "Password Reset Template",
"subject" : "{{.FirstName}}, please reset your password.",
"text" : "Please reset your password here: {{.URL}}",
"html" : "<html><head></head><body>Please reset your password <a href\"{{.URL}}\">here</a></body></html>",
"modified_date" : "2016-11-21T18:30:11.1477736-06:00",
"attachments" : [],
}
400: Bad Request
At least one text or HTML field must be specified, otherwise a 400: Bad Request error is returned
{
"message": "Need to specify at least plaintext or HTML content",
"success": false,
"data": null
}

This method expects the template to be provided in JSON format. You must provide a template name and the text and/or html for the template.

Importing an Existing Email

What better way to make pixel-perfect emails than by importing an existing email you already have in your inbox?

Using the Import Email endpoint, you can take a raw email and parse it as a valid Gophish template.

To add tracking, make sure you specify a {{.Tracker}} in the html field. The UI adds this automatically, but it needs to be specified if you're using the API.

This method returns the JSON representation of the template that was created.

put
Modify Template

https://localhost:3333
/api/templates/:id
Modifies an existing template.
Request
Response
Path Parameters
id
required
integer
The template ID to modify
Headers
Authorization
required
string
A valid API key
Body Parameters
Payload
required
object
The JSON representation of the template you wish to modify. The entire template must be provided, not just the fields you wish to update.
200: OK

This method expects the template to be provided in JSON format. You must provide a full template, not just the fields you want to update.

This method returns the JSON representation of the template that was modified.

delete
Delete Template

https://localhost:3333
/api/templates/:id
Deletes a template by ID.
Request
Response
Path Parameters
optional
string
200: OK
{
"message": "Template deleted successfully!",
"success": true,
"data": null
}
404: Not Found
If no template is found with the provided ID, a 404: Not Found error is returned
{
"message": "Template not found",
"success": false,
"data": null
}

Returns a 404 error if the specified template isn't found.

This method returns a status message indicating the template was deleted successfully.

post
Import Template

https://localhost:3333
/api/import/email
Imports an email as a template.
Request
Response
Headers
Authorization
required
string
A valid API key
Body Parameters
convert_links
required
boolean
Whether or not to convert the links within the email to {{.URL}} automatically.
content
required
string
The original email content in RFC 2045 format, including the original headers.
200: OK
{
"text": "Email text",
"html": "Email HTML",
"subject": "Email subject"
}

Gophish provides the ability to parse an existing email to be used as a template. This makes it easy to repurpose legitimate emails for your phishing assessments.

This endpoint expects the raw email content in RFC 2045 format, including the original headers. Usually, this is found using the "Show Original" feature of email clients.

The request body for this endpoint is a JSON request in the form of:

{
content: string
convert_links: boolean
}

By setting the convert_links attribute to true, Gophish will automatically change all the links in the email to {{.URL}}.

Note: This method doesn't fully import the email as a template. Instead, it parses the email, returning a response that can be used with the "Create Template" endpoint.