diff --git a/templates/docs.html b/templates/docs.html index 0932e5b8..8f9e493b 100644 --- a/templates/docs.html +++ b/templates/docs.html @@ -1,6 +1,6 @@ {{ define "base" }} -Gophish API Back to top

Gophish API

Gophish was built from the ground-up with a JSON API that makes it easy for developers and sysadmins to automate simulated phishing campaigns.

-

These docs describe how to use the gophish API.

+Gophish API

Gophish API

API Endpoint
http://localhost:3333/api

Gophish was built from the ground-up with a JSON API that makes it easy for developers and sysadmins to automate simulated phishing campaigns.

+

These docs describe how to use the gophish API.

Authorization

All API requests require the use of a generated API key. You can find your API key, or generate a new one, by navigating to the /settings endpoint, or clicking the “Settings” sidebar item.

@@ -13,14 +13,14 @@ "data": null }
-

Campaigns

Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign.

+

Campaigns

Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign.

Campaigns have the following attributes:

  • -

    id : 1 (required, number) - Unique identifier

    +

    id : 1 (number, required) - Unique identifier

  • -

    name : Example Campaign (required) - Title of Campaign

    +

    name : Example Campaign (string, required) - Title of Campaign

  • created_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was created

    @@ -35,24 +35,62 @@

    page : Page (required) - Landing page for users who click the phishing link

  • -

    status : Emails Sent (required, string) - The current status of the campaign

    +

    status : Emails Sent (string) - The current status of the campaign

  • -

    results : Attributes (ResultsList)

    +

    results : array[Result] - List of Results for the campaign

  • -

    timeline : Attributes (EventList)

    +

    timeline : array[Event] - List of Events for the campaign

  • -

    smtp : Attributes (SMTP)

    +

    smtp : SMTP

  • url : http://foo.bar (required, string) - The URL used in the Template sent to us ers

-

Campaigns

Get Campaigns
GET/campaigns

Get a list of campaigns.

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
+
The results of the campaign are stored in the results field. Each result has the following attributes:

+
    
+
  • 
+
    id : 1 (number, required) - Unique identifier
    
+
    • 
+
  • 
+
    email : foo@example.com - Email address of the target
    
+
    • 
+
  • 
+
    first_name : John - First name of the target
    
+
    • 
+
  • 
+
    last_name : Doe - Last name of the target
    
+
    • 
+
  • 
+
    status : Email Sent - The status of the result
    
+
    • 
+
  • 
+
    ip : 1.2.3.4 - The IP address that created the event (if any)
    
+
    • 
+
  • 
+
    latitude : 0.0000- The latitude of the IP address
    
+
    • 
+
  • 
+
    longitude : 0.0000 - The longitude of the IP address
    
+
    • 
+

+
Each campaign also keeps a timeline of events that occur, such as clicking a link, opening an email, etc. These events each have the following attributes:

+
    
+
  • 
+
    email : foo@example.com - Email address of the target
    
+
    • 
+
  • 
+
    time : 2015-1-1T01:02:03.000000Z (datetime) - The timestamp the event was created
    
+
    • 
+
  • 
+
    message : Campaign Created (string) - The event message
    
+
    • 
+

+

Campaigns

GET http://localhost:3333/api/campaigns
Responses200404
Headers
Content-Type: application/json
Body
[
   {
     "id": 1,
     "name": "Example Campaign",
@@ -64,7 +102,14 @@ ers

       "subject": "Example email template subject",
       "text": "This is a test message!",
       "html": "<html><head></head><body>This is a test message!</body></html>",
-      "attachments": [],
+      "attachments": [
+        {
+          "id": 1,
+          "name": "Example Attachment",
+          "content": "Hello, world!",
+          "type": "text/plain"
+        }
+      ],
       "modified_date": "2015-01-01T01:02:03.000000Z"
     },
     "page": {
@@ -74,18 +119,40 @@ ers

       "modified_date": "2015-01-01T01:02:03.000000Z"
     },
     "status": "Emails Sent",
-    "results": [],
-    "timeline": [],
+    "results": [
+      {
+        "id": 1,
+        "email": "foo@example.com",
+        "first_name": "John",
+        "last_name": "Doe",
+        "status": "Email Sent",
+        "ip": "1.2.3.4",
+        "latitude": 0,
+        "longitude": 0
+      }
+    ],
+    "timeline": [
+      {
+        "id": 1,
+        "email": "foo@example.com",
+        "time": "2015-01-01T01:02:03.000000Z",
+        "message": "Campaign Created"
+      }
+    ],
     "smtp": {
-      "id": 1
+      "id": 1,
+      "host": "smtp.example.com:25",
+      "username": "foo",
+      "password": "bar",
+      "from_address": "John Doe <foo@example.com>"
     },
     "url": "http://foo.bar"
   }
 ]
Schema
{
-  "type": "array",
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Create New Campaign
POST/campaigns

Create a new campaign

-
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Campaigns
GET/campaigns

Get a list of campaigns.

+
POST http://localhost:3333/api/campaigns
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Campaign",
   "created_date": "2015-01-01T01:02:03.000000Z",
@@ -96,7 +163,14 @@ ers

     "subject": "Example email template subject",
     "text": "This is a test message!",
     "html": "<html><head></head><body>This is a test message!</body></html>",
-    "attachments": [],
+    "attachments": [
+      {
+        "id": 1,
+        "name": "Example Attachment",
+        "content": "",
+        "type": "text/plain"
+      }
+    ],
     "modified_date": "2015-01-01T01:02:03.000000Z"
   },
   "page": {
@@ -106,13 +180,92 @@ ers

     "modified_date": "2015-01-01T01:02:03.000000Z"
   },
   "status": "Emails Sent",
-  "results": [],
-  "timeline": [],
+  "results": [
+    {
+      "id": 1,
+      "email": "foo@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "status": "Email Sent",
+      "ip": "1.2.3.4",
+      "latitude": 0,
+      "longitude": 0
+    }
+  ],
+  "timeline": [
+    {
+      "id": 1,
+      "email": "foo@example.com",
+      "time": "2015-01-01T01:02:03.000000Z",
+      "message": "Campaign Created"
+    }
+  ],
   "smtp": {
-    "id": 1
+    "id": 1,
+    "host": "smtp.example.com:25",
+    "username": "foo",
+    "password": "bar",
+    "from_address": "John Doe <foo@example.com>"
+  },
+  "url": "http://foo.bar"
+}
Responses201400
Headers
Content-Type: application/json
Body
{
+  "id": 1,
+  "name": "Example Campaign",
+  "created_date": "2015-01-01T01:02:03.000000Z",
+  "completed_date": "2015-01-01T01:02:03.000000Z",
+  "template": {
+    "id": 1,
+    "name": "Example Template",
+    "subject": "Example email template subject",
+    "text": "This is a test message!",
+    "html": "<html><head></head><body>This is a test message!</body></html>",
+    "attachments": [
+      {
+        "id": 1,
+        "name": "Example Attachment",
+        "content": "Hello, world!",
+        "type": "text/plain"
+      }
+    ],
+    "modified_date": "2015-01-01T01:02:03.000000Z"
+  },
+  "page": {
+    "id": 1,
+    "name": "Example Page",
+    "html": "<html><head></head><body>This is a test message!</body></html>",
+    "modified_date": "2015-01-01T01:02:03.000000Z"
+  },
+  "status": "Emails Sent",
+  "results": [
+    {
+      "id": 1,
+      "email": "foo@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "status": "Email Sent",
+      "ip": "1.2.3.4",
+      "latitude": 0,
+      "longitude": 0
+    }
+  ],
+  "timeline": [
+    {
+      "id": 1,
+      "email": "foo@example.com",
+      "time": "2015-01-01T01:02:03.000000Z",
+      "message": "Campaign Created"
+    }
+  ],
+  "smtp": {
+    "id": 1,
+    "host": "smtp.example.com:25",
+    "username": "foo",
+    "password": "bar",
+    "from_address": "John Doe <foo@example.com>"
   },
   "url": "http://foo.bar"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -199,10 +352,12 @@ ers

       "description": "The current status of the campaign"
     },
     "results": {
-      "type": "array"
+      "type": "array",
+      "description": "The results of the campaign"
     },
     "timeline": {
-      "type": "array"
+      "type": "array",
+      "description": "The event timeline"
     },
     "smtp": {
       "type": "object",
@@ -210,11 +365,32 @@ ers

         "id": {
           "type": "number",
           "description": "Unique identifier"
+        },
+        "host": {
+          "type": "string",
+          "description": "The hostname and port for the SMTP server"
+        },
+        "username": {
+          "type": "string",
+          "description": "The username used for SMTP authentication"
+        },
+        "password": {
+          "type": "string",
+          "description": "The password used for SMTP authentication"
+        },
+        "from_address": {
+          "type": "string",
+          "description": "The \"From\" address to spoof"
         }
       },
       "required": [
-        "id"
-      ]
+        "id",
+        "host",
+        "username",
+        "password",
+        "from_address"
+      ],
+      "description": "The SMTP settings used in the campaign"
     },
     "url": {
       "type": "string",
@@ -226,156 +402,13 @@ ers

     "name",
     "status",
     "url"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
-  "id": 1,
-  "name": "Example Campaign",
-  "created_date": "2015-01-01T01:02:03.000000Z",
-  "completed_date": "2015-01-01T01:02:03.000000Z",
-  "template": {
-    "id": 1,
-    "name": "Example Template",
-    "subject": "Example email template subject",
-    "text": "This is a test message!",
-    "html": "<html><head></head><body>This is a test message!</body></html>",
-    "attachments": [],
-    "modified_date": "2015-01-01T01:02:03.000000Z"
-  },
-  "page": {
-    "id": 1,
-    "name": "Example Page",
-    "html": "<html><head></head><body>This is a test message!</body></html>",
-    "modified_date": "2015-01-01T01:02:03.000000Z"
-  },
-  "status": "Emails Sent",
-  "results": [],
-  "timeline": [],
-  "smtp": {
-    "id": 1
-  },
-  "url": "http://foo.bar"
-}
Schema
{
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "number",
-      "description": "Unique identifier"
-    },
-    "name": {
-      "type": "string",
-      "description": "Title of Campaign"
-    },
-    "created_date": {
-      "type": "string",
-      "description": "Date the Campaign was created"
-    },
-    "completed_date": {
-      "type": "string",
-      "description": "Date the Campaign was completed"
-    },
-    "template": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "number",
-          "description": "Unique identifier"
-        },
-        "name": {
-          "type": "string",
-          "description": "Name of template"
-        },
-        "subject": {
-          "type": "string",
-          "description": "Subject of email sent to users"
-        },
-        "text": {
-          "type": "string",
-          "description": "Raw text of email sent to users"
-        },
-        "html": {
-          "type": "string",
-          "description": "HTML of email sent to users"
-        },
-        "attachments": {
-          "type": "array",
-          "description": "The attachments sent with the email template"
-        },
-        "modified_date": {
-          "type": "string",
-          "description": "Date the Template was last modified"
-        }
-      },
-      "required": [
-        "id",
-        "name"
-      ]
-    },
-    "page": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "number",
-          "description": "Unique identifier"
-        },
-        "name": {
-          "type": "string",
-          "description": "Name of Page"
-        },
-        "html": {
-          "type": "string",
-          "description": "HTML of the landing page users hit when clicking links in the email template"
-        },
-        "modified_date": {
-          "type": "string",
-          "description": "Date the Page was last modified"
-        }
-      },
-      "required": [
-        "id",
-        "name",
-        "html"
-      ]
-    },
-    "status": {
-      "type": "string",
-      "description": "The current status of the campaign"
-    },
-    "results": {
-      "type": "array"
-    },
-    "timeline": {
-      "type": "array"
-    },
-    "smtp": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "number",
-          "description": "Unique identifier"
-        }
-      },
-      "required": [
-        "id"
-      ]
-    },
-    "url": {
-      "type": "string",
-      "description": "The URL used in the Template sent to users"
-    }
-  },
-  "required": [
-    "id",
-    "name",
-    "status",
-    "url"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
   "data": "Any associated data"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "message": {
@@ -383,17 +416,15 @@ ers

       "description": "The detailed error message"
     },
     "success": {
-      "type": "string",
+      "type": "boolean",
       "description": "The success status of the request"
     },
     "data": {
       "type": "string"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Campaign

Get Campaign
GET/campaigns/{id}

Get a campaign by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Campaign ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  }
+}

Create New Campaign
POST/campaigns

Create a new campaign.

+

Campaign

GET http://localhost:3333/api/campaigns/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Campaign",
   "created_date": "2015-01-01T01:02:03.000000Z",
@@ -404,7 +435,14 @@ ers

     "subject": "Example email template subject",
     "text": "This is a test message!",
     "html": "<html><head></head><body>This is a test message!</body></html>",
-    "attachments": [],
+    "attachments": [
+      {
+        "id": 1,
+        "name": "Example Attachment",
+        "content": "Hello, world!",
+        "type": "text/plain"
+      }
+    ],
     "modified_date": "2015-01-01T01:02:03.000000Z"
   },
   "page": {
@@ -414,13 +452,36 @@ ers

     "modified_date": "2015-01-01T01:02:03.000000Z"
   },
   "status": "Emails Sent",
-  "results": [],
-  "timeline": [],
+  "results": [
+    {
+      "id": 1,
+      "email": "foo@example.com",
+      "first_name": "John",
+      "last_name": "Doe",
+      "status": "Email Sent",
+      "ip": "1.2.3.4",
+      "latitude": 0,
+      "longitude": 0
+    }
+  ],
+  "timeline": [
+    {
+      "id": 1,
+      "email": "foo@example.com",
+      "time": "2015-01-01T01:02:03.000000Z",
+      "message": "Campaign Created"
+    }
+  ],
   "smtp": {
-    "id": 1
+    "id": 1,
+    "host": "smtp.example.com:25",
+    "username": "foo",
+    "password": "bar",
+    "from_address": "John Doe <foo@example.com>"
   },
   "url": "http://foo.bar"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -507,10 +568,12 @@ ers

       "description": "The current status of the campaign"
     },
     "results": {
-      "type": "array"
+      "type": "array",
+      "description": "The results of the campaign"
     },
     "timeline": {
-      "type": "array"
+      "type": "array",
+      "description": "The event timeline"
     },
     "smtp": {
       "type": "object",
@@ -518,11 +581,32 @@ ers

         "id": {
           "type": "number",
           "description": "Unique identifier"
+        },
+        "host": {
+          "type": "string",
+          "description": "The hostname and port for the SMTP server"
+        },
+        "username": {
+          "type": "string",
+          "description": "The username used for SMTP authentication"
+        },
+        "password": {
+          "type": "string",
+          "description": "The password used for SMTP authentication"
+        },
+        "from_address": {
+          "type": "string",
+          "description": "The \"From\" address to spoof"
         }
       },
       "required": [
-        "id"
-      ]
+        "id",
+        "host",
+        "username",
+        "password",
+        "from_address"
+      ],
+      "description": "The SMTP settings used in the campaign"
     },
     "url": {
       "type": "string",
@@ -534,41 +618,42 @@ ers

     "name",
     "status",
     "url"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Headers
Content-Type: application/json
Body
{
   "message": "Campaign not found",
   "success": false,
   "data": null
-}

Delete a Campaign
DELETE/campaigns/{id}

Delete a campaign by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Campaign ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "Page deleted successfully!",
+}

Get Campaign
GET/campaigns/{id}

Get a campaign by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Campaign ID

+
DELETE http://localhost:3333/api/campaigns/1
Responses200404
Headers
Content-Type: application/json
Body
{
+  "message": "Campaign deleted successfully!",
   "success": true,
   "data": null
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+}
Headers
Content-Type: application/json
Body
{
   "message": "Campaign not found",
   "success": false,
   "data": null
-}

Templates

Templates define what email content is sent to targets during campaigns. It contains the subject of the email as well as the HTML and text content of the email.

+}

Delete a Campaign
DELETE/campaigns/{id}

Delete a campaign by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Campaign ID

+

Templates

Templates define what email content is sent to targets during campaigns. It contains the subject of the email as well as the HTML and text content of the email.

  • -

    id: 1 (required, number) - Unique identifier

    +

    id: 1 (number, required) - Unique identifier

  • -

    name: Example Template (required) - Name of template

    +

    name: Example Template (string, required) - Name of template

  • -

    subject: Example email template subject - Subject of email sent to users

    +

    subject: Example email template subject (string) - Subject of email sent to users

  • -

    text: This is a test message! - Raw text of email sent to users

    +

    text: This is a test message! (string) - Raw text of email sent to users

  • -

    html: <html><head></head><body>This is a test message!</body></html> - HTML of email sent to users

    +

    html: <html><head></head><body>This is a test message!</body></html> (string) - HTML of email sent to users

  • -

    attachments: Attributes (AttachmentList) - The attachments sent with the email template

    +

    attachments: array[Attachment] - The attachments sent with the email template

  • modified_date: 2015-01-01T01:02:03.000000Z (string) - Date the Template was last modified

    @@ -590,35 +675,44 @@ ers

    type: text/plain - MIME type of the Attachment

-

Templates

Get Templates
GET/templates

Get a list of templates.

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
+

Templates

GET http://localhost:3333/api/templates
Responses200404
Headers
Content-Type: application/json
Body
[
   {
     "id": 1,
     "name": "Example Template",
     "subject": "Example email template subject",
     "text": "This is a test message!",
     "html": "<html><head></head><body>This is a test message!</body></html>",
-    "attachments": [],
+    "attachments": [
+      {
+        "id": 1,
+        "name": "Example Attachment",
+        "content": "Hello, world!",
+        "type": "text/plain"
+      }
+    ],
     "modified_date": "2015-01-01T01:02:03.000000Z"
   }
 ]
Schema
{
-  "type": "array",
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Create New Template
POST/templates

Create a new template

-
-

Importing an Existing Email

-

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

-

Using the Import Email endpoint, you can take a raw email and import it as a template into gophish.

-
-
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Templates
GET/templates

Get a list of templates.

+
POST http://localhost:3333/api/templates
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Template",
   "subject": "Example email template subject",
   "text": "This is a test message!",
   "html": "<html><head></head><body>This is a test message!</body></html>",
-  "attachments": [],
+  "attachments": [
+    {
+      "id": 1,
+      "name": "Example Attachment",
+      "content": "Hello, world!",
+      "type": "text/plain"
+    }
+  ],
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -653,17 +747,24 @@ ers

   "required": [
     "id",
     "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Responses201400
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Template",
   "subject": "Example email template subject",
   "text": "This is a test message!",
   "html": "<html><head></head><body>This is a test message!</body></html>",
-  "attachments": [],
+  "attachments": [
+    {
+      "id": 1,
+      "name": "Example Attachment",
+      "content": "Hello, world!",
+      "type": "text/plain"
+    }
+  ],
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -698,13 +799,13 @@ ers

   "required": [
     "id",
     "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
   "data": "Any associated data"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "message": {
@@ -712,25 +813,36 @@ ers

       "description": "The detailed error message"
     },
     "success": {
-      "type": "string",
+      "type": "boolean",
       "description": "The success status of the request"
     },
     "data": {
       "type": "string"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Template

Get Template
GET/templates/{id}

Get a template by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Template ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  }
+}

Create New Template
POST/templates

Create a new template

+
+

Importing an Existing Email

+

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

+

Using the Import Email endpoint, you can take a raw email and import it as a template into gophish.

+
+

Template

GET http://localhost:3333/api/templates/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Template",
   "subject": "Example email template subject",
   "text": "This is a test message!",
   "html": "<html><head></head><body>This is a test message!</body></html>",
-  "attachments": [],
+  "attachments": [
+    {
+      "id": 1,
+      "name": "Example Attachment",
+      "content": "Hello, world!",
+      "type": "text/plain"
+    }
+  ],
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -765,23 +877,24 @@ ers

   "required": [
     "id",
     "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Headers
Content-Type: application/json
Body
{
   "message": "Template not found",
   "success": false,
   "data": null
-}

Delete a Template
DELETE/templates/{id}

Delete a template by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Template ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+}

Get Template
GET/templates/{id}

Get a template by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Template ID

+
DELETE http://localhost:3333/api/templates/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "message": "Template deleted successfully!",
   "success": true,
   "data": null
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+}
Headers
Content-Type: application/json
Body
{
   "message": "Template not found",
   "success": false,
   "data": null
-}

Groups

Groups contain the details for one or more users targeted in the simulated phishing campaign. Groups contain the following attributes:

+}

Delete a Template
DELETE/templates/{id}

Delete a template by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Template ID

+

Groups

Groups contain the details for one or more users targeted in the simulated phishing campaign. Groups contain the following attributes:

Each target contains the following attributes:

@@ -815,28 +928,28 @@ ers

-

Have A Lot of Users to Import?

+

Have A Lot of Users to Import?

If you have all your targets in a CSV file, you can bulk import them into a group using the Import CSV endpoint.

In the future, we plan to add other importation methods to make setting up groups a breeze.

-

Groups

Get Groups
GET/groups

Get a list of groups.

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
+

Groups

GET http://localhost:3333/api/groups
Responses200404
Headers
Content-Type: application/json
Body
[
   {
     "id": 1,
     "name": "Example Group",
     "modified_date": "2015-01-01T01:02:03.000000Z",
-    "targets": []
+    "targets": "array[Target]"
   }
 ]
Schema
{
-  "type": "array",
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Create New Group
POST/groups

Create a new group

-
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Groups
GET/groups

Get a list of groups.

+
POST http://localhost:3333/api/groups
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Group",
   "modified_date": "2015-01-01T01:02:03.000000Z",
-  "targets": []
+  "targets": "array[Target]"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -852,20 +965,22 @@ ers

       "description": "Date the Group was last modified"
     },
     "targets": {
-      "type": "array"
+      "type": "string",
+      "description": "The targets in the group"
     }
   },
   "required": [
     "id",
-    "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
+    "name",
+    "targets"
+  ]
+}
Responses201400
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Group",
   "modified_date": "2015-01-01T01:02:03.000000Z",
-  "targets": []
+  "targets": "array[Target]"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -881,19 +996,21 @@ ers

       "description": "Date the Group was last modified"
     },
     "targets": {
-      "type": "array"
+      "type": "string",
+      "description": "The targets in the group"
     }
   },
   "required": [
     "id",
-    "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
+    "name",
+    "targets"
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
   "data": "Any associated data"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "message": {
@@ -901,22 +1018,21 @@ ers

       "description": "The detailed error message"
     },
     "success": {
-      "type": "string",
+      "type": "boolean",
       "description": "The success status of the request"
     },
     "data": {
       "type": "string"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Group

Get Group
GET/groups/{id}

Get a group by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Group ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  }
+}

Create New Group
POST/groups

Create a new group

+

Group

GET http://localhost:3333/api/groups/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Group",
   "modified_date": "2015-01-01T01:02:03.000000Z",
-  "targets": []
+  "targets": "array[Target]"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -932,29 +1048,32 @@ ers

       "description": "Date the Group was last modified"
     },
     "targets": {
-      "type": "array"
+      "type": "string",
+      "description": "The targets in the group"
     }
   },
   "required": [
     "id",
-    "name"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+    "name",
+    "targets"
+  ]
+}
Headers
Content-Type: application/json
Body
{
   "message": "Group not found",
   "success": false,
   "data": null
-}

Delete a Group
DELETE/groups/{id}

Delete a Group by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Template ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+}

Get Group
GET/groups/{id}

Get a group by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Group ID

+
DELETE http://localhost:3333/api/groups/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "message": "Group deleted successfully!",
   "success": true,
   "data": null
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+}
Headers
Content-Type: application/json
Body
{
   "message": "Group not found",
   "success": false,
   "data": null
-}

Pages

Pages are the HTML page that a user lands on after clicking on a phishing link.

+}

Delete a Group
DELETE/groups/{id}

Delete a Group by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Template ID

+

Pages

Pages are the HTML page that a user lands on after clicking on a phishing link.

-

Importing a Site

+

Importing a Site

Let gophish do the hard work for you in importing a site. By using the Import Site endpoint, you can simply give gophish a URL and have the site imported for you.

-

Pages

Get Pages
GET/pages

Get a list of pages.

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
+

Pages

GET http://localhost:3333/api/pages
Responses200404
Headers
Content-Type: application/json
Body
[
   {
     "id": 1,
     "name": "Example Page",
@@ -982,15 +1100,16 @@ ers

     "modified_date": "2015-01-01T01:02:03.000000Z"
   }
 ]
Schema
{
-  "type": "array",
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Create New Page
POST/pages

Create a new page

-
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
[]

Get Pages
GET/pages

Get a list of pages.

+
POST http://localhost:3333/api/pages
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Page",
   "html": "<html><head></head><body>This is a test message!</body></html>",
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -1014,14 +1133,14 @@ ers

     "id",
     "name",
     "html"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Responses201400
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Page",
   "html": "<html><head></head><body>This is a test message!</body></html>",
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -1045,13 +1164,13 @@ ers

     "id",
     "name",
     "html"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
   "data": "Any associated data"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "message": {
@@ -1059,22 +1178,21 @@ ers

       "description": "The detailed error message"
     },
     "success": {
-      "type": "string",
+      "type": "boolean",
       "description": "The success status of the request"
     },
     "data": {
       "type": "string"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Page

Get Page
GET/pages/{id}

Get a page by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Page ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+  }
+}

Create New Page
POST/pages

Create a new page

+

Page

GET http://localhost:3333/api/pages/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "id": 1,
   "name": "Example Page",
   "html": "<html><head></head><body>This is a test message!</body></html>",
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -1098,19 +1216,20 @@ ers

     "id",
     "name",
     "html"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Headers
Content-Type: application/json
Body
{
   "message": "Page not found",
   "success": false,
   "data": null
-}

Put Page
PUT/pages

Modify a page by its ID.

-
Request
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+}

Get Page
GET/pages/{id}

Get a page by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Page ID

+
PUT http://localhost:3333/api/pages
Requestsexample 1
Body
{
   "id": 1,
   "name": "Example Page",
   "html": "<html><head></head><body>This is a test message!</body></html>",
   "modified_date": "2015-01-01T01:02:03.000000Z"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "id": {
@@ -1134,24 +1253,111 @@ ers

     "id",
     "name",
     "html"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Responses200404400
Headers
Content-Type: application/json
Body
{
+  "id": 1,
+  "name": "Example Page",
+  "html": "<html><head></head><body>This is a test message!</body></html>",
+  "modified_date": "2015-01-01T01:02:03.000000Z"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number",
+      "description": "Unique identifier"
+    },
+    "name": {
+      "type": "string",
+      "description": "Name of Page"
+    },
+    "html": {
+      "type": "string",
+      "description": "HTML of the landing page users hit when clicking links in the email template"
+    },
+    "modified_date": {
+      "type": "string",
+      "description": "Date the Page was last modified"
+    }
+  },
+  "required": [
+    "id",
+    "name",
+    "html"
+  ]
+}
Headers
Content-Type: application/json
Body
{
   "message": "Page not found",
   "success": false,
   "data": null
-}

Delete a Page
DELETE/pages/{id}

Delete a page by its ID.

-
Parameters
HideShow
id
number (required) Example: 1

The Page ID

-
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
+  "data": "Any associated data"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "The detailed error message"
+    },
+    "success": {
+      "type": "boolean",
+      "description": "The success status of the request"
+    },
+    "data": {
+      "type": "string"
+    }
+  }
+}

Put Page
PUT/pages

Modify a page by its ID.

+
DELETE http://localhost:3333/api/pages/1
Responses200404
Headers
Content-Type: application/json
Body
{
   "message": "Page deleted successfully!",
   "success": true,
   "data": null
-}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
+}
Headers
Content-Type: application/json
Body
{
   "message": "Page not found",
   "success": false,
   "data": null
-}

Import

Import functions facilitate the ability to import emails, groups and more using simple interfaces.

-

Group

Import a Group
POST/import/group

This endpoint allows you to import a group from a CSV.

+}

Delete a Page
DELETE/pages/{id}

Delete a page by its ID.

+
URI Parameters
HideShow
id
number (required) Example: 1

The Page ID

+

Import

Import functions facilitate the ability to import emails, groups and more using simple interfaces.

+

Group

POST http://localhost:3333/api/import/group
Requestsexample 1
Headers
Content-Type: multipart/form-data; boundary=----BOUNDARY
Body
------BOUNDARY
+Content-Disposition: form-data; name="files[]"; filename="filename.csv"
+Content-Type: application/vnd.ms-excel
+
+[File Content]
+------BOUNDARY
Responses201400
Headers
Content-Type: application/json
Body
[
+  {
+    "id": 1,
+    "first_name": "John",
+    "last_name": "Doe",
+    "email": "john.doe@example.com",
+    "position": "System Administrator"
+  }
+]
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array"
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
+  "data": "Any associated data"
+}
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "string",
+      "description": "The detailed error message"
+    },
+    "success": {
+      "type": "boolean",
+      "description": "The success status of the request"
+    },
+    "data": {
+      "type": "string"
+    }
+  }
+}

Import a Group
POST/import/group

This endpoint allows you to import a group from a CSV.

The fields expected in the CSV are as follows:

-
Request
HideShow
Headers
Content-Type: multipart/form-data; boundary=----BOUNDARY
Body
------BOUNDARY
-Content-Disposition: form-data; name="files[]"; filename="filename.csv"
-Content-Type: application/vnd.ms-excel
-
-[File Content]
-------BOUNDARY
Response  201
HideShow
Headers
Content-Type: application/json
Body
[
-  {
-    "id": 1,
-    "first_name": "John",
-    "last_name": "Doe",
-    "email": "john.doe@example.com",
-    "position": "System Administrator"
-  }
-]
Schema
{
-  "type": "array",
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
-  "data": "Any associated data"
-}
Schema
{
-  "type": "object",
-  "properties": {
-    "message": {
-      "type": "string",
-      "description": "The detailed error message"
-    },
-    "success": {
-      "type": "string",
-      "description": "The success status of the request"
-    },
-    "data": {
-      "type": "string"
-    }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Email

Import an Email
POST/import/email

This endpoint allows you to parse and import an email in RFC 5322 format.

-

You can use this endpoint to easily import an email that you have received legitimately to re-use it for simulated phishing.

-
Request
HideShow
Headers
Content-Type: text/plain
Body
MIME-Version: 1.0
+

Email

POST http://localhost:3333/api/import/email
Requestsexample 1
Headers
Content-Type: text/plain
Body
MIME-Version: 1.0
 Date: Fri, 25 Dec 2015 21:22:28 -0600
 Subject: Foo Bar
 From: John Doe <john.doe@example.com>
@@ -1225,11 +1393,12 @@ Content-Type: text/html; charset=UTF-8
 
 <div dir="ltr">Foo bar</div>
 
---14dae9473639dc6b2a0527c4945f--
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
+--14dae9473639dc6b2a0527c4945f--
Responses201400
Headers
Content-Type: application/json
Body
{
   "text": "Foo bar",
   "html": "\"\\u003cdiv\\u003eFoo bar\\u003c/div\\u003e\"",
   "subject": "Foo Bar"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "text": {
@@ -1244,13 +1413,13 @@ Content-Type: text/html; charset=UTF-8
       "type": "string",
       "description": "The email subject"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
+  }
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
   "data": "Any associated data"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "message": {
@@ -1258,19 +1427,19 @@ Content-Type: text/html; charset=UTF-8
       "description": "The detailed error message"
     },
     "success": {
-      "type": "string",
+      "type": "boolean",
       "description": "The success status of the request"
     },
     "data": {
       "type": "string"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Site

Import a Site
POST/import/site

Imports a site via the URL. This causes gophish to reach out to the site and pull down the HTML of the URL given.

-

To keep styles, images, and Javascript setup and working, gophish adds a base tag to the returned HTML pointing to the original site.

-
Request
HideShow
Headers
Content-Type: application/json
Body
{
+  }
+}

Import an Email
POST/import/email

This endpoint allows you to parse and import an email in RFC 5322 format.

+

You can use this endpoint to easily import an email that you have received legitimately to re-use it for simulated phishing.

+

Site

POST http://localhost:3333/api/import/site
Requestsexample 1
Headers
Content-Type: application/json
Body
{
   "url": "http://foo.bar"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "url": {
@@ -1280,11 +1449,11 @@ Content-Type: text/html; charset=UTF-8
   },
   "required": [
     "url"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
+  ]
+}
Responses201400
Headers
Content-Type: application/json
Body
{
   "html": "<html><head></head><body>This is a test message!</body></html>"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "html": {
@@ -1294,13 +1463,13 @@ Content-Type: text/html; charset=UTF-8
   },
   "required": [
     "html"
-  ],
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
-  "message": "\"Error message\"",
-  "success": "false",
+  ]
+}
Headers
Content-Type: application/json
Body
{
+  "message": "Error message",
+  "success": false,
   "data": "Any associated data"
 }
Schema
{
+  "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
     "message": {
@@ -1308,15 +1477,16 @@ Content-Type: text/html; charset=UTF-8
       "description": "The detailed error message"
     },
     "success": {
-      "type": "string",
+      "type": "boolean",
       "description": "The success status of the request"
     },
     "data": {
       "type": "string"
     }
-  },
-  "$schema": "http://json-schema.org/draft-04/schema#"
-}

Generated by aglio on 27 Dec 2015