Gophish API

API Endpoint

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 ¶

GET http://localhost:3333/api/campaigns

Responses200404

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>",
      "ignore_cert_errors": false
    },
    "url": "http://foo.bar"
  }
]

Schema

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

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

Campaigns have the following attributes:

id : 1 (number, required) - Unique identifier
name : Example Campaign (string, 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 (string) - The current status of the campaign
results : array[Result] - List of Results for the campaign
timeline : array[Event] - List of Events for the campaign
smtp : SendingProfile
url : http://foo.bar (required, string) - The URL used in the Template sent to us ers

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

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",
  "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": "",
        "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>",
    "ignore_cert_errors": false
  },
  "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>",
    "ignore_cert_errors": false
  },
  "url": "http://foo.bar"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/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",
      "description": "The results of the campaign"
    },
    "timeline": {
      "type": "array",
      "description": "The event timeline"
    },
    "smtp": {
      "type": "object",
      "properties": {
        "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"
        },
        "ignore_cert_errors": {
          "type": "boolean",
          "description": "Whether or not to ignore certificate errors"
        }
      },
      "required": [
        "id",
        "host",
        "username",
        "password",
        "from_address"
      ],
      "description": "The Sending Profile settings used in the campaign"
    },
    "url": {
      "type": "string",
      "description": "The URL used in the Template sent to users"
    }
  },
  "required": [
    "id",
    "name",
    "status",
    "url"
  ]
}

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

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",
  "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>",
    "ignore_cert_errors": false
  },
  "url": "http://foo.bar"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/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",
      "description": "The results of the campaign"
    },
    "timeline": {
      "type": "array",
      "description": "The event timeline"
    },
    "smtp": {
      "type": "object",
      "properties": {
        "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"
        },
        "ignore_cert_errors": {
          "type": "boolean",
          "description": "Whether or not to ignore certificate errors"
        }
      },
      "required": [
        "id",
        "host",
        "username",
        "password",
        "from_address"
      ],
      "description": "The Sending Profile settings used in the campaign"
    },
    "url": {
      "type": "string",
      "description": "The URL used in the Template sent to users"
    }
  },
  "required": [
    "id",
    "name",
    "status",
    "url"
  ]
}

Headers

Content-Type: application/json

Body

{
  "message": "Campaign not found",
  "success": false,
  "data": null
}

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
}

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.

URI Parameters

HideShow

id: number (required) Example: 1
The Campaign ID

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

Headers

Content-Type: application/json

Body

[]

Get Templates
GET`/templates`

Get a list of 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 (number, required) - Unique identifier
name: Example Template (string, required) - Name of template
subject: Example email template subject (string) - Subject 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> (string) - HTML of email sent to users
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

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

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

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

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

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

Headers

Content-Type: application/json

Body

{
  "message": "Template not found",
  "success": false,
  "data": null
}

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
}

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.

URI Parameters

HideShow

id: number (required) Example: 1
The Template ID

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": "array[Target]"
  }
]

Schema

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

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 (array[Target]) (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.

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": "array[Target]"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/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": "string",
      "description": "The targets in the group"
    }
  },
  "required": [
    "id",
    "name",
    "targets"
  ]
}

Responses201400

Headers

Content-Type: application/json

Body

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

Schema

{
  "$schema": "http://json-schema.org/draft-04/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": "string",
      "description": "The targets in the group"
    }
  },
  "required": [
    "id",
    "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": {
      "type": "string",
      "description": "The detailed error message"
    },
    "success": {
      "type": "boolean",
      "description": "The success status of the request"
    },
    "data": {
      "type": "string"
    }
  }
}

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": "array[Target]"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/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": "string",
      "description": "The targets in the group"
    }
  },
  "required": [
    "id",
    "name",
    "targets"
  ]
}

Headers

Content-Type: application/json

Body

{
  "message": "Group not found",
  "success": false,
  "data": null
}

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
}

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.

URI Parameters

HideShow

id: number (required) Example: 1
The Template ID

Sending Profiles ¶

GET http://localhost:3333/api/smtp

Responses200404

Headers

Content-Type: application/json

Body

[
  {
    "id": 1,
    "host": "smtp.example.com:25",
    "username": "foo",
    "password": "bar",
    "from_address": "John Doe <foo@example.com>",
    "ignore_cert_errors": false
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Headers

Content-Type: application/json

Body

[]

Get Sending Profiles
GET`/smtp`

Get a list of sending profiles.

Sending profiles contain the details for SMTP or other settings used to control how emails are sent in campaigns. Sending profiles contain the following attributes:

id: 1 (required, number) - Unique identifier
name: Example Profile (string, required) - Name of the Sending Profile
interface: SMTP (string) - Interface type of the sending profile. By default, this is “SMTP”
host: 1.1.1.1:25 (string, required) - The hostname:port for the SMTP configuration
username: foo (string) - The username to authenticate to the SMTP server (optional)
password: bar (string) - The password to authenticate to the SMTP server (optional)
from_address: Foo Bar foo.bar@example.com (string) - The email address to use in the “From” header. This is typically used to spoof email addresses
ignore_cert_errors: false (boolean) - Whether or not to disable certificate validation when connecting to the SMTP server via TLS
modified_date: 2015-01-01T01:02:03.000000Z (string) - Date the Group was last modified

Receiving Certificate Errors?

It’s common to have an SMTP server that is configured using a self-signed or otherwise untrusted SSL certficate. To avoid errors when connecting to the server, set ignore_cert_errors to “true”.

POST http://localhost:3333/api/smtp

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "host": "smtp.example.com:25",
  "username": "foo",
  "password": "bar",
  "from_address": "John Doe <foo@example.com>",
  "ignore_cert_errors": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "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"
    },
    "ignore_cert_errors": {
      "type": "boolean",
      "description": "Whether or not to ignore certificate errors"
    }
  },
  "required": [
    "id",
    "host",
    "username",
    "password",
    "from_address"
  ]
}

Responses201400

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "host": "smtp.example.com:25",
  "username": "foo",
  "password": "bar",
  "from_address": "John Doe <foo@example.com>",
  "ignore_cert_errors": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "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"
    },
    "ignore_cert_errors": {
      "type": "boolean",
      "description": "Whether or not to ignore certificate errors"
    }
  },
  "required": [
    "id",
    "host",
    "username",
    "password",
    "from_address"
  ]
}

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

Create New Sending Profile
POST`/smtp`

Create a new sending profile

Sending Profile ¶

GET http://localhost:3333/api/smtp/1

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "host": "smtp.example.com:25",
  "username": "foo",
  "password": "bar",
  "from_address": "John Doe <foo@example.com>",
  "ignore_cert_errors": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "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"
    },
    "ignore_cert_errors": {
      "type": "boolean",
      "description": "Whether or not to ignore certificate errors"
    }
  },
  "required": [
    "id",
    "host",
    "username",
    "password",
    "from_address"
  ]
}

Headers

Content-Type: application/json

Body

{
  "message": "SMTP not found",
  "success": false,
  "data": null
}

Get Sending Profile
GET`/smtp/{id}`

Get a sending profile by its ID.

URI Parameters

HideShow

id: number (required) Example: 1
The sending profile ID

DELETE http://localhost:3333/api/smtp/1

Responses200404

Headers

Content-Type: application/json

Body

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

Headers

Content-Type: application/json

Body

{
  "message": "SMTP not found",
  "success": false,
  "data": null
}

Delete a Sending Profile
DELETE`/smtp/{id}`

Delete a Sending Profile by its ID.

URI Parameters

HideShow

id: number (required) Example: 1
The Sending Profile ID

Pages ¶

GET http://localhost:3333/api/pages

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": "array"
}

Headers

Content-Type: application/json

Body

[]

Get Pages
GET`/pages`

Get a list of 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.

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

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

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

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

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
}

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
}

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.

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:

First Name
Last Name
Position
Email
Company

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

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

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 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": {
      "type": "string",
      "description": "The URL to be retrieved"
    }
  },
  "required": [
    "url"
  ]
}

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

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

Generated by aglio on 04 Mar 2016

API Endpoint

Authorization ¶

Campaigns ¶

Campaigns ¶

Headers

Body

Schema

Headers

Body

Get CampaignsGET/campaigns

Headers

Body

Headers

Body

Schema

Headers

Body

Schema

Create New CampaignPOST/campaigns

Campaign ¶

Headers

Body

Schema

Headers

Body

Get CampaignGET/campaigns/{id}

Headers

Body

Headers

Body

Delete a CampaignDELETE/campaigns/{id}

Templates ¶

Templates ¶

Headers

Body

Schema

Headers

Body

Get TemplatesGET/templates

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Create New TemplatePOST/templates

Template ¶

Headers

Body

Schema

Headers

Body

Get TemplateGET/templates/{id}

Headers

Body

Headers

Body

Delete a TemplateDELETE/templates/{id}

Groups ¶

Groups ¶

Headers

Body

Schema

Headers

Body

Get GroupsGET/groups

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Create New GroupPOST/groups

Group ¶

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`

Get Template
GET`/templates/{id}`

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

Get Groups
GET`/groups`

Create New Group
POST`/groups`

Get Group
GET`/groups/{id}`

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

Get Sending Profiles
GET`/smtp`

Create New Sending Profile
POST`/smtp`

Get Sending Profile
GET`/smtp/{id}`

Delete a Sending Profile
DELETE`/smtp/{id}`

Get Pages
GET`/pages`

Create New Page
POST`/pages`

Get Page
GET`/pages/{id}`