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.

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.

When making requests, simply append the api_key=[API_KEY] as a GET parameter to authorize yourself to the API.

GET /api/campaigns/?api_key=12345678901234567890123456789012

If no API key is provided, you’ll receive the following response when attempting to make requests to API endpoints:

{
  "message": "API Key not set",
  "success": false,
  "data": null
}

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
name : Example Campaign (required) - Title of Campaign
created_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was created
completed_date : 2015-1-1T01:02:03.000000Z (datetime) - Date the Campaign was completed
template : Template
page : Page (required) - Landing page for users who click the phishing link
status : Emails Sent (required, string) - The current status of the campaign
results : Attributes (ResultsList)
timeline : Attributes (EventList)
smtp : Attributes (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

[
  {
    "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": "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

{
  "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 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",
  "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#"
}

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

{
  "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 404

HideShow

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!",
  "success": true,
  "data": null
}

Response 404

HideShow

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.

id: 1 (required, number) - Unique identifier
name: Example Template (required) - Name of template
subject: Example email template subject - Subject of email sent to users
text: This is a test message! - 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
attachments: Attributes (AttachmentList) - The attachments sent with the email template
modified_date: 2015-01-01T01:02:03.000000Z (string) - Date the Template was last modified

You can also attach files or payloads to the emails that you send. These are attached as a list of Attachment objects.

Attachments have the following attributes:

id: 1 (required, number) - Unique identifier
name: Example Attachment (required) - Filename of Attachment
content: Base64 encoded attachment content
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

[
  {
    "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"
  }
]

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

{
  "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"
}

Schema

{
  "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"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 201

HideShow

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": [],
  "modified_date": "2015-01-01T01:02:03.000000Z"
}

Schema

{
  "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"
  ],
  "$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#"
}

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

{
  "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"
}

Schema

{
  "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"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

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

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

Response 404

HideShow

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:

id: 1 (required, number) - Unique identifier
name: Example Group (required) - Name of the Group
modified_date: 2015-01-01T01:02:03.000000Z (string) - Date the Group was last modified
targets: Attributes (TargetList) (required) - The targets in the group

Each target contains the following attributes:

id: 1 (required, number) - Unique identifier
first_name: John - First name of Target
last_name: Doe - Last name of Target
email: john.doe@example.com - Email address of Target
position: System Administrator - Company position of the Target

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

[
  {
    "id": 1,
    "name": "Example Group",
    "modified_date": "2015-01-01T01:02:03.000000Z",
    "targets": []
  }
]

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

{
  "id": 1,
  "name": "Example Group",
  "modified_date": "2015-01-01T01:02:03.000000Z",
  "targets": []
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique identifier"
    },
    "name": {
      "type": "string",
      "description": "Name of the Group"
    },
    "modified_date": {
      "type": "string",
      "description": "Date the Group was last modified"
    },
    "targets": {
      "type": "array"
    }
  },
  "required": [
    "id",
    "name"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "name": "Example Group",
  "modified_date": "2015-01-01T01:02:03.000000Z",
  "targets": []
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique identifier"
    },
    "name": {
      "type": "string",
      "description": "Name of the Group"
    },
    "modified_date": {
      "type": "string",
      "description": "Date the Group was last modified"
    },
    "targets": {
      "type": "array"
    }
  },
  "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",
  "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#"
}

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

{
  "id": 1,
  "name": "Example Group",
  "modified_date": "2015-01-01T01:02:03.000000Z",
  "targets": []
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique identifier"
    },
    "name": {
      "type": "string",
      "description": "Name of the Group"
    },
    "modified_date": {
      "type": "string",
      "description": "Date the Group was last modified"
    },
    "targets": {
      "type": "array"
    }
  },
  "required": [
    "id",
    "name"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

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

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

Response 404

HideShow

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.

id: 1 (required, number) - Unique identifier
name: Example Page (required, string) - Name of Page
html: <html><head></head><body>This is a test message!</body></html> (required, string) - HTML of the landing page users hit when clicking links in the email template
modified_date: 2015-01-01T01:02:03.000000Z (string) - Date the Page was last modified

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

[
  {
    "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

{
  "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

{
  "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

{
  "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"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 201

HideShow

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

{
  "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"
  ],
  "$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#"
}

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

{
  "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

{
  "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"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

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

{
  "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

{
  "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"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

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

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

Response 404

HideShow

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.

The fields expected in the CSV are as follows:

First Name
Last Name
Position
Email
Company

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
Date: Fri, 25 Dec 2015 21:22:28 -0600
Subject: Foo Bar
From: John Doe <john.doe@example.com>
To: Jane Doe <jane.doe@example.com>
Content-Type: multipart/alternative; boundary=14dae9473639dc6b2a0527c4945f

--14dae9473639dc6b2a0527c4945f
Content-Type: text/plain; charset=UTF-8

Foo bar

--14dae9473639dc6b2a0527c4945f
Content-Type: text/html; charset=UTF-8

<div dir="ltr">Foo bar</div>

--14dae9473639dc6b2a0527c4945f--

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "text": "Foo bar",
  "html": "\"\\u003cdiv\\u003eFoo bar\\u003c/div\\u003e\"",
  "subject": "Foo Bar"
}

Schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "The email text part"
    },
    "html": {
      "type": "string",
      "description": "The email HTML part"
    },
    "subject": {
      "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",
  "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#"
}

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

{
  "url": "http://foo.bar"
}

Schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to be retrieved"
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "html": "<html><head></head><body>This is a test message!</body></html>"
}

Schema

{
  "type": "object",
  "properties": {
    "html": {
      "type": "string",
      "description": "HTML of the requested URL."
    }
  },
  "required": [
    "html"
  ],
  "$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#"
}

Authorization ¶

Campaigns¶

Campaigns¶

Get CampaignsGET/campaigns

Headers

Body

Schema

Create New CampaignPOST/campaigns

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Campaign¶

Get CampaignGET/campaigns/{id}

Headers

Body

Schema

Headers

Body

Delete a CampaignDELETE/campaigns/{id}

Headers

Body

Headers

Body

Templates¶

Templates¶

Get TemplatesGET/templates

Headers

Body

Schema

Create New TemplatePOST/templates

Importing an Existing Email ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Template¶

Get TemplateGET/templates/{id}

Headers

Body

Schema

Headers

Body

Delete a TemplateDELETE/templates/{id}

Headers

Body

Headers

Body

Groups¶

Have A Lot of Users to Import? ¶

Groups¶

Get GroupsGET/groups

Headers

Body

Schema

Create New GroupPOST/groups

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Group¶

Get GroupGET/groups/{id}

Headers

Body

Schema

Authorization

Get Campaigns
GET`/campaigns`

Create New Campaign
POST`/campaigns`

Get Campaign
GET`/campaigns/{id}`

Delete a Campaign
DELETE`/campaigns/{id}`

Get Templates
GET`/templates`

Create New Template
POST`/templates`

Importing an Existing Email

Get Template
GET`/templates/{id}`

Delete a Template
DELETE`/templates/{id}`

Have A Lot of Users to Import?

Get Groups
GET`/groups`

Create New Group
POST`/groups`

Get Group
GET`/groups/{id}`

Delete a Group
DELETE`/groups/{id}`

Importing a Site

Get Pages
GET`/pages`

Create New Page
POST`/pages`

Get Page
GET`/pages/{id}`

Put Page
PUT`/pages`

Delete a Page
DELETE`/pages/{id}`

Import a Group
POST`/import/group`

Import an Email
POST`/import/email`

Import a Site
POST`/import/site`