Campaigns

Campaigns have the following structure:

  {
    "id"               : int,
    "name"             : string,
    "created_date"     : string(datetime),
    "launch_date"      : string(datetime),
    "send_by_date"     : string(datetime),
    "completed_date"   : string(datetime),
    "status"           : string,
    "results"          : []Result,
    "groups"           : []Group,
    "smtp"             : {
      "id"                 : int,
      "interface_type"     : string,
      "name"               : string,
      "host"               : string,
      "from_address"       : string,
      "ignore_cert_errors" : bool,
      "headers"            : []Header,
      "modified_date"      : string(datetime)
    },
    "scenarios"        : []Scenario,
    "customer"         : {}Customer,
    "customer_id"      : int,
    "repeat_delay"     : string,
    "parent_id"        : int,
    "total_targets"    : int,
    "sensibilisation_type" : string
  }

Campaign Events

Gottaphish keeps track of every event for a campaign in it's timeline. Each event has the following format:

{
  "id"          : int64,
  "campaign_id" : int64,
  "email"       : string,
  "time"        : string(datetime),
  "message"     : string,
  "details"     : string,
  "rid"         : string
}

The details field is a string containing JSON which contains the raw data about an event (such as credentials that were submitted, user-agent information, and more). The details field has the following format:

{
  payload              : object
  browser              : object
}

Campaign Results

In addition to this, campaign results are maintained in the results attribute. This has a format similar to the members of a Group, in that they have the following structure:

{
  "id"              : int64,
  "status"          : string,
  "ip"              : string,
  "latitude"        : float,
  "longitude"       : float,
  "send_date"       : string(datetime),
  "reported"        : bool,
  "modified_date"   : string(datetime),
  "scenario_id"     : int64,
  "scenario"        : {}Scenario | null,
  "scenario_value"  : {}ScenarioValue,
  "email"           : string,
  "first_name"      : string,
  "last_name"       : string,
  "position"        : string,
  "language"        : string,
  "target_id"       : int
}

Get Campaigns

GET /api/campaigns/

Returns a list of campaigns.

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

  {
    "id": 1,
    "name": "Example Campaign",
    "created_date": "2018-10-08T15:56:29.48815Z",
    "launch_date": "2018-10-08T15:56:00Z",
    "send_by_date": "0001-01-01T00:00:00Z",
    "completed_date": "0001-01-01T00:00:00Z",
    "status": "In progress",
    "results": [],
    "groups": [],
    "smtp": 
      {
        "id": 4,
        "interface_type": "Email",
        "name": "Send email",
        "host": "127.0.0.1:8025",
        "from_address": "[email protected]",
        "ignore_cert_errors": true,
        "headers": [],
        "modified_date": "0001-01-01T00:00:00Z"
      },
    "Scenarios": [],
    "customer": {},
    "customerId": 138,
    "repeat_delay": "",
    "parent_id": 0,
    "total_targets": 1,
    "sensibilisation_type": "",
  }  

Get Campaign

GET /api/campaigns/:id

Returns a campaign given an ID.

Path Parameters

Name	Type	Description
id*	integer	The campaign ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

[
  {
    "id": 1,
    "name": "Example Campaign",
    "created_date": "2018-10-08T15:56:29.48815Z",
    "launch_date": "2018-10-08T15:56:00Z",
    "send_by_date": "0001-01-01T00:00:00Z",
    "completed_date": "0001-01-01T00:00:00Z",
    "status": "In progress",
    "results": [],
    "groups": [],
    "smtp": 
      {
        "id": 4,
        "interface_type": "Email",
        "name": "Send email",
        "host": "127.0.0.1:8025",
        "from_address": "[email protected]",
        "ignore_cert_errors": true,
        "headers": [],
        "modified_date": "0001-01-01T00:00:00Z"
      },
    "Scenarios": [],
    "customer": {},
    "customerId": 138,
    "repeat_delay": "",
    "parent_id": 0,
    "total_targets": 1,
    "sensibilisation_type": "",
  }  
]

404

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

Create Campaign

POST /api/campaigns/

Creates and launches a new campaign.

Headers

Name	Type	Description
Authorization*	string	A valid API key

Request Body

Name	Type	Description
Payload*	object	The campaign details. See the introduction above for the format of a campaign.

201

[
  {
    "id": 1,
    "name": "Example Campaign",
    "created_date": "2018-10-08T15:56:29.48815Z",
    "launch_date": "2018-10-08T15:56:00Z",
    "send_by_date": "0001-01-01T00:00:00Z",
    "completed_date": "0001-01-01T00:00:00Z",
    "status": "In progress",
    "results": [],
    "groups": [],
    "smtp": 
      {
        "id": 4,
        "interface_type": "Email",
        "name": "Send email",
        "host": "127.0.0.1:8025",
        "from_address": "[email protected]",
        "ignore_cert_errors": true,
        "headers": [],
        "modified_date": "0001-01-01T00:00:00Z"
      },
    "Scenarios": [],
    "customer": {},
    "customerId": 138,
    "repeat_delay": "",
    "parent_id": 0,
    "total_targets": 1,
    "sensibilisation_type": "",
  }  
]

This method expects the campaign to be provided in JSON format. For the various objects in a campaign, such as the scenario, landing page, or sending profile, you need to provide the name attribute. Here's an example of a JSON payload to create a new campaign:

{
    "name":"CC Example Campaign",
    "launch_date":"2018-10-08T16:20:00+00:00",
    "scenario":[{"id": 1}],
    "send_by_date":"2018-10-08T16:20:00+00:00",
    "customer":[{"id": 138}],
    "groups":[{"id": 111}],
    "smtp":{"name":"Example Sending Profile"},
}

Scheduling a Campaign

You can schedule a campaign to launch at a later time. To do this, simply put the desired time you want the campaign to launch in the launch_date attribute. Gophish expects the date to be provided in ISO8601 format.

Without setting a launch date, Gophish launches the campaign immediately.

Spreading out Emails

By default, Gophish sends all the emails in a campaign as quickly as possible. Instead, you may wish to spread emails out over a period of hours or days. This is possible by setting the send_by_dat, (the "During" attribute) to an ISO8601 formatted datetime. It's important to note that this must be after the launch_date.

Get Campaign Results

GET /api/campaigns/:id/results

Gets the results for a campaign.

Path Parameters

Name	Type	Description
id*	integer	The campaign ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

[
  {
    "id": 1,
    "name": "Example Campaign",
    "created_date": "2018-10-08T15:56:29.48815Z",
    "launch_date": "2018-10-08T15:56:00Z",
    "send_by_date": "0001-01-01T00:00:00Z",
    "completed_date": "0001-01-01T00:00:00Z",
    "status": "In progress",
    "results": [
        {
          "id": "Io1YGLhb3q5Q",
          "status": "Sending",
          "ip": "",
          "latitude": 0,
          "longitude": 0,
          "send_date": "2018-10-08T11:50:30Z",
          "reported": false,
          "modified_date": "2018-10-09T11:50:30Z",
          "scenario_id": null,
          "scenario": null,
          "scenario_value": {},
          "email": "[email protected]",
          "first_name": "Example",
          "last_name": "User",
          "position": "Systems Administrator",
          "language": "French",
          "target_id": 866
        },
    ],
    "groups": [],
    "smtp": 
      {
        "id": 4,
        "interface_type": "Email",
        "name": "Send email",
        "host": "127.0.0.1:8025",
        "from_address": "[email protected]",
        "ignore_cert_errors": true,
        "headers": [],
        "modified_date": "0001-01-01T00:00:00Z"
      },
    "Scenarios": [],
    "customer": {},
    "customerId": 138,
    "repeat_delay": "",
    "parent_id": 0,
    "total_targets": 1,
    "sensibilisation_type": "",
  }  
]

404

You may not always want the full campaign details, including the scenarios, landing page, etc. Instead, you may just want to poll the campaign results for updates. This API endpoint only returns information that's relevant to the campaign results.

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

Get Campaign Summary

GET api/campaigns/:id/summary

Returns summary information about a campaign.

Path Parameters

Name	Type	Description
id*	integer	The campaign ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

{
  "id": 1,
  "created_date": "2018-10-08T15:56:29.48815Z",
  "launch_date": "2018-10-08T15:56:00Z",
  "send_by_date": "0001-01-01T00:00:00Z",
  "completed_date": "0001-01-01T00:00:00Z",
  "status": "In progress",
  "repeat_delay": "",
  "name": "Example Campaign",
  "stats": {
    "total": 2,
    "sent": 2,
    "opened": 1,
    "clicked": 1,
    "submitted_data": 0,
    "email_reported": 0,
    "error": 0,
  },
  "customer": "",
  "customer_id": 0,
  "organisation_id": 0,
  "parent_id": 0,
  "count_targets": 0,
  "sensibilisation_type": ""
}

404

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

There may be cases where you aren't interested in the specific results, but rather want high-level statistics, or a "summary", about a campaign.

The response includes a stats object which has the following format:

{
  total            : int64
  EmailsSent       : int64
  OpenedEmail      : int64
  ClickedLink      : int64
  SubmittedData    : int64
  EmailReported    : int64
  Error            : int64
}

Delete Campaign

DELETE /api/campaigns/:id

Deletes a campaign by ID.

Path Parameters

Name	Type	Description
id*	integer	The campaign ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

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

404

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

Complete Campaign

GET /api/campaigns/:id/complete

Marks a campaign as complete.

Path Parameters

Name	Type	Description
id*	integer	The campaign ID

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

{
  "message": "Campaign completed successfully!",
  "success": true,
  "data": null
}