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

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 : Attributes (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.

Caution

If the value for title or body is null or undefined, then the corresponding value is not modified on the server. However, if you send an empty string instead then it will permanently overwrite the original value.

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
}

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

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.

Caution

If the value for title or body is null or undefined, then the corresponding value is not modified on the server. However, if you send an empty string instead then it will permanently overwrite the original value.

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
}

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

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.

Caution

If the value for title or body is null or undefined, then the corresponding value is not modified on the server. However, if you send an empty string instead then it will permanently overwrite the original value.

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": "Group not found",
  "success": false,
  "data": null
}

Pages

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

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

Get Pages
GET/pages

Get a list of templates.

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/{id}

Modify 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": "Group not found",
  "success": false,
  "data": null
}

Delete a Page
DELETE/pages/{id}

Delete a page by its ID.

Caution

If the value for title or body is null or undefined, then the corresponding value is not modified on the server. However, if you send an empty string instead then it will permanently overwrite the original value.

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": "Group not found",
    "success": false,
    "data": null
}
{
    "error": "Template not found"
}

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:

  • Test

  • two

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

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

Generated by aglio on 26 Dec 2015

{{end}}