Scenarios

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

Additionally, scenarios can contain tracking images so that Gottaphish knows when the user opens the email.

Scenarios have the following structure:

{
  "id"                    : int64,
  "name"                  : string,
  "language"              : string,
  "template"              : {}Template,
  "template_id"           : int64,
  "preview"               : string,
  "service_used"          : {}ServiceUsed,
  "service_used_id"       : int64,
  "labels"                : string,
  "customer"              : {}Customer,
  "customer_id"           : int64,
  "user_id"               : int64,
  "modified_date"         : string(datetime),
  "type_of_action"        : string,
  "description"           : string,
  "campaigns"             : []Campaign,
  "scenario_request_log"  : {}ScenarioRequestLog,
  "scenario_request_log_id": int64,
}

Scenarios support sending attachments. Attachments have the following structure:

  "id"            : int64,
  "template_id"   : int64,
  "content"       : string,
  "type"          : string,
  "name"          : string,

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

Get Scenarios

GET /api/scenarios/?customer_id=X

Returns a list of scenarios.

Where X is the customer ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

[
  {
    "id" : 1,
    "name" : "Password Reset Template",
    "language": "french",
    "template": {},
    "template_id": 139,
    "preview": "iVBORw0KGgoAAAANSUhEUgAAAAUA",
    "serviceused": {},
    "serviceusedId": 15,
    "labels": "{\"job\": \"\"}",
    "customer": {},
    "customerId": 138,
    "user_id": 2,
    "modified_date": "2016-11-21T18:30:11.1477736-06:00",
    "typeofaction": "Click",
    "description": "",
    "Campaigns": null,
    "scenario_request_log": {},
    "scenario_request_log_id": 141,
    "hash_ia": "",
    "sensibilisation_type": "simulation"
  }
]

Get Scenario

GET /api/scenario/:id

Returns a scenario with the provided ID.

Returns a 404: Not Found error if the specified scenario doesn't exist.

Path Parameters

Name	Type	Description
id*	integer	The scenario ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

 {
    "id" : 1,
    "name" : "Password Reset Template",
    "language": "french",
    "template": {},
    "template_id": 139,
    "preview": "iVBORw0KGgoAAAANSUhEUgAAAAUA",
    "serviceused": {},
    "serviceusedId": 15,
    "labels": "{\"job\": \"\"}",
    "customer": {},
    "customerId": 138,
    "user_id": 2,
    "modified_date": "2016-11-21T18:30:11.1477736-06:00",
    "typeofaction": "Click",
    "description": "",
    "Campaigns": null,
    "scenario_request_log": {},
    "scenario_request_log_id": 141,
    "hash_ia": "",
    "sensibilisation_type": "simulation"
  }

404

Create Scenario

POST /api/scenarios

Creates a new scenario from the provided JSON request body.

Headers

Name	Type	Description
Authorization*	string	A valid API key

Request Body

Name	Type	Description
Payload*	object	The request body should be a JSON representation of a scenario. See the schema at the top of this page for the scenario format.

201

 {
    "name" : "Password Reset Template",
    "language": "french",
    "template": {},
    "template_id": 139,
    "preview": "iVBORw0KGgoAAAANSUhEUgAAAAUA",
    "serviceused": {},
    "serviceusedId": 15,
    "labels": "{\"job\": \"\"}",
    "customer": {},
    "customerId": 138,
    "user_id": 2,
    "modified_date": "2016-11-21T18:30:11.1477736-06:00",
    "typeofaction": "Click",
    "description": "",
    "Campaigns": null,
    "scenario_request_log": {},
    "scenario_request_log_id": 141,
    "hash_ia": "",
    "sensibilisation_type": "simulation"
  }

400

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

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 Gottaphish scenario.

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 scenario that was created.

Create Scenario with AI

POST /api/scenariosLogRequests/

Creates a new scenario with AI from the provided JSON request body.

For one specific target :

{
    "status": "submit",
    "target_type": "target",
    "target_id": 30648,
    "environment_ids": "[{\"id\": 146}, {\"id\": 147}]",
    "language": "french",
    "response_type": "Click",
    "temperature": 7,
    "difficulty": 85,
    "customer_id": 1,
    "user_id": 1
}

For generic use :

{
    "status": "submit",
    "target_type": "generic",
    "target_id": null,
    "environment_ids": "[{\"id\": 146}, {\"id\": 147}]",
    "language": "french",
    "response_type": "Click",
    "temperature": 7,
    "difficulty": 85,
    "customer_id": 1,
    "user_id": 1
} 

Retrieve the associated scenario

GET /api/scenariosLogRequest/1068

200

{
    "id": 1068,
    "status": "processed",
    "generated_error": "",
    "target_type": "generic",
    "target_id": 0,
    "environment_ids": "[{\"id\":146}]",
    "language": "french",
    "response_type": "Click",
    "temperature": 7,
    "difficulty": 85,
    "ai_model": "gpt-4",
    "request_time": "2024-11-26T10:04:23Z",
    "completion_time": "2024-11-26T10:05:00Z",
    "customer_id": 1,
    "user_id": 1,
    "scenario_id": 812
}

When the scenario request log is "Processed" you can retrieve the new created scenario with scenario_id by GET /api/scenario/:id

Modify Scenario

PUT /api/scenarios/:id

Modifies an existing scenario.

Path Parameters

Name	Type	Description
id*	integer	The scenario ID to modify

Headers

Name	Type	Description
Authorization*	string	A valid API key

Request Body

Name	Type	Description
Payload*	object	The JSON representation of the scenario you wish to modify. The entire scenario must be provided, not just the fields you wish to update.

200

 {
    "id" : 1,
    "name" : "Password Reset Template",
    "language": "french",
    "template": {},
    "template_id": 139,
    "preview": "iVBORw0KGgoAAAANSUhEUgAAAAUA",
    "serviceused": {},
    "serviceusedId": 15,
    "labels": "{\"job\": \"\"}",
    "customer": {},
    "customerId": 138,
    "user_id": 2,
    "modified_date": "2016-11-21T18:30:11.1477736-06:00",
    "typeofaction": "Click",
    "description": "",
    "Campaigns": null,
    "scenario_request_log": {},
    "scenario_request_log_id": 141,
    "hash_ia": "",
    "sensibilisation_type": "simulation"
  }

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

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

Delete Scenario

DELETE /api/scenarios/:id

Deletes a scenario by ID.

Path Parameters

Name	Type	Description
	string

200

{
  "message": "Scenario deleted successfully!",
  "success": true,
  "data": null
}

404

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

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

Import Scenario

POST /api/import/email

Imports an email as a scenario.

Headers

Name	Type	Description
Authorization*	string	A valid API key

Request Body

Name	Type	Description
convert:links*	boolean	Whether or not to convert the links within the email to {{.URL}} automatically.
content*	string	The original email content in RFC 2045 format, including the original headers.

200

{
  "text": "Email text",
  "html": "Email HTML",
  "subject": "Email subject"
}

Gottaphish provides the ability to parse an existing email to be used as a scenario. 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, Gottaphish 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.