2015-12-26 04:09:32 +00:00
FORMAT: 1A
2016-01-12 04:29:11 +00:00
HOST: http://localhost:3333/api
2015-12-26 04:09:32 +00:00
# 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.
2016-01-12 04:29:11 +00:00
These docs describe how to use the [gophish](https://github.com/gophish/gophish) API.
2015-12-26 04:09:32 +00:00
::: note
## 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.
```http
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:
```json
{
"message": "API Key not set",
"success": false,
"data": null
}
```
:::
# Group Campaigns
2016-03-04 02:44:11 +00:00
## Campaigns [/campaigns/]
### Get Campaigns [GET]
Get a list of campaigns.
2015-12-26 04:09:32 +00:00
Campaigns object contain the resources needed for gophish to launch and track a simulated phishing campaign.
Campaigns have the following attributes:
2016-01-06 04:16:21 +00:00
+ ```id``` : 1 (number, required) - Unique identifier
+ ```name``` : Example Campaign (string, required) - Title of Campaign
2015-12-26 04:09:32 +00:00
+ ```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
2015-12-27 02:48:10 +00:00
+ ```template``` : [Template](#templates)
+ ```page``` : [Page](#pages) (required) - Landing page for users who click the phishing link
2016-01-12 04:29:11 +00:00
+ ```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
2016-03-04 02:44:11 +00:00
+ ```smtp``` : [SendingProfile](#sending-profiles)
2015-12-26 04:09:32 +00:00
+ ```url``` : http://foo.bar (required, string) - The URL used in the Template sent to us
ers
2016-01-12 04:29:11 +00:00
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
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2016-01-12 04:29:11 +00:00
+ Attributes (array[Campaign])
+ Response 404 (application/json)
+ Body
[]
2015-12-26 04:09:32 +00:00
### Create New Campaign [POST]
2016-01-12 04:29:11 +00:00
Create a new campaign.
2015-12-26 04:09:32 +00:00
+ Attributes (Campaign)
+ Request (application/json)
+ Response 201 (application/json)
+ Attributes (Campaign)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Campaign [/campaigns/{id}]
### Get Campaign [GET]
Get a campaign by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Campaign ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
+ Attributes (Campaign)
+ Response 404 (application/json)
+ Body
{
"message": "Campaign not found",
"success": false,
"data": null
}
### Delete a Campaign [DELETE]
Delete a campaign by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Campaign ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2015-12-27 02:48:10 +00:00
+ Body
{
2016-01-12 04:29:11 +00:00
"message": "Campaign deleted successfully!",
2015-12-27 02:48:10 +00:00
"success": true,
"data": null
}
2015-12-26 04:09:32 +00:00
+ Response 404 (application/json)
+ Body
{
"message": "Campaign not found",
"success": false,
"data": null
}
# Group Templates
2016-03-04 02:44:11 +00:00
## Templates [/templates/]
### Get Templates [GET]
Get a list of templates.
2015-12-26 04:09:32 +00:00
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.
2016-01-06 04:16:21 +00:00
+ ```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
2016-01-12 04:29:11 +00:00
+ ```attachments```: array[Attachment] - The attachments sent with the email template
2015-12-26 04:09:32 +00:00
+ ```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
+ Response 200 (application/json)
2016-01-12 04:29:11 +00:00
+ Attributes (array[Template])
+ Response 404 (application/json)
+ Body
[]
2015-12-26 04:09:32 +00:00
### Create New Template [POST]
Create a new template
2015-12-27 02:48:10 +00:00
::: note
2016-01-06 04:16:21 +00:00
**Importing an Existing Email**
2015-12-27 02:48:10 +00:00
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](#import-email) endpoint, you can take a raw email and import it as a template into gophish.
:::
2015-12-26 04:09:32 +00:00
+ Request (application/json)
+ Attributes (Template)
+ Response 201 (application/json)
+ Attributes (Template)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Template [/templates/{id}]
### Get Template [GET]
Get a template by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Template ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
+ Attributes (Template)
+ Response 404 (application/json)
+ Body
{
"message": "Template not found",
"success": false,
"data": null
}
### Delete a Template [DELETE]
Delete a template by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Template ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2015-12-27 02:48:10 +00:00
+ Body
{
"message": "Template deleted successfully!",
"success": true,
"data": null
}
2015-12-26 04:09:32 +00:00
+ Response 404 (application/json)
+ Body
{
"message": "Template not found",
"success": false,
"data": null
}
# Group Groups
2016-03-04 02:44:11 +00:00
## Groups [/groups/]
### Get Groups [GET]
Get a list of groups.
2015-12-26 04:09:32 +00:00
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
2016-01-12 04:29:11 +00:00
+ ```targets```: Attributes (array[Target]) (required) - The targets in the group
2015-12-26 04:09:32 +00:00
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
2015-12-27 02:48:10 +00:00
::: note
2016-01-06 04:16:21 +00:00
**Have A Lot of Users to Import?**
2015-12-27 02:48:10 +00:00
If you have all your targets in a CSV file, you can bulk import them into a group using the [Import CSV](#import-group) endpoint.
In the future, we plan to add other importation methods to make setting up groups a breeze.
:::
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2016-01-12 04:29:11 +00:00
+ Attributes (array[Group])
+ Response 404 (application/json)
+ Body
[]
2015-12-26 04:09:32 +00:00
### Create New Group [POST]
Create a new group
+ Request (application/json)
+ Attributes (Group)
+ Response 201 (application/json)
+ Attributes (Group)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Group [/groups/{id}]
### Get Group [GET]
Get a group by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Group ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
+ Attributes (Group)
+ Response 404 (application/json)
+ Body
{
"message": "Group not found",
"success": false,
"data": null
}
### Delete a Group [DELETE]
Delete a Group by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Template ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2015-12-27 02:48:10 +00:00
+ Body
{
"message": "Group deleted successfully!",
"success": true,
"data": null
}
2015-12-26 04:09:32 +00:00
+ Response 404 (application/json)
+ Body
{
"message": "Group not found",
"success": false,
"data": null
}
2016-03-04 02:44:11 +00:00
# Group Sending Profiles
## Sending Profiles [/smtp/]
### Get Sending Profiles [GET]
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
::: note
**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".
:::
+ Response 200 (application/json)
+ Attributes (array[SendingProfile])
+ Response 404 (application/json)
+ Body
[]
### Create New Sending Profile [POST]
Create a new sending profile
+ Request (application/json)
+ Attributes (SendingProfile)
+ Response 201 (application/json)
+ Attributes (SendingProfile)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Sending Profile [/smtp/{id}]
### Get Sending Profile [GET]
Get a sending profile by its ID.
+ Parameters
+ id: `1` (number, required) - The sending profile ID
+ Response 200 (application/json)
+ Attributes (SendingProfile)
+ Response 404 (application/json)
+ Body
{
"message": "SMTP not found",
"success": false,
"data": null
}
### Delete a Sending Profile [DELETE]
Delete a Sending Profile by its ID.
+ Parameters
+ id: `1` (number, required) - The Sending Profile ID
+ Response 200 (application/json)
+ Body
{
"message": "SMTP deleted successfully!",
"success": true,
"data": null
}
+ Response 404 (application/json)
+ Body
{
"message": "SMTP not found",
"success": false,
"data": null
}
2015-12-26 04:09:32 +00:00
# Group Pages
2016-03-04 02:44:11 +00:00
## Pages [/pages/]
### Get Pages [GET]
Get a list of pages.
2015-12-26 04:09:32 +00:00
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
2015-12-27 02:48:10 +00:00
::: note
2016-01-06 04:16:21 +00:00
**Importing a Site**
2015-12-27 02:48:10 +00:00
Let gophish do the hard work for you in importing a site. By using the [Import Site](#import-site) endpoint, you can simply give gophish a URL and have the site imported for you.
:::
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2016-01-12 04:29:11 +00:00
+ Attributes (array[Page])
+ Response 404 (application/json)
+ Body
[]
2015-12-26 04:09:32 +00:00
### Create New Page [POST]
Create a new page
+ Request (application/json)
+ Attributes (Page)
+ Response 201 (application/json)
+ Attributes (Page)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Page [/pages/{id}]
### Get Page [GET]
Get a page by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Page ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
+ Attributes (Page)
+ Response 404 (application/json)
+ Body
{
"message": "Page not found",
"success": false,
"data": null
}
### Put Page [PUT]
Modify a page by its ID.
+ Request
+ Attributes (Page)
+ Response 200 (application/json)
+ Attributes (Page)
+ Response 404 (application/json)
+ Body
{
2015-12-27 02:48:10 +00:00
"message": "Page not found",
2015-12-26 04:09:32 +00:00
"success": false,
"data": null
}
2016-01-12 04:29:11 +00:00
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
2015-12-26 04:09:32 +00:00
### Delete a Page [DELETE]
Delete a page by its ID.
+ Parameters
2016-01-06 04:16:21 +00:00
+ id: `1` (number, required) - The Page ID
2015-12-26 04:09:32 +00:00
+ Response 200 (application/json)
2015-12-27 02:48:10 +00:00
+ Body
{
"message": "Page deleted successfully!",
"success": true,
"data": null
}
2015-12-26 04:09:32 +00:00
+ Response 404 (application/json)
+ Body
{
2015-12-27 02:48:10 +00:00
"message": "Page not found",
2015-12-26 04:09:32 +00:00
"success": false,
"data": null
}
# Group Import
Import functions facilitate the ability to import emails, groups and more using simple interfaces.
## Group [/import/group]
### Import a Group [POST]
This endpoint allows you to import a group from a CSV.
The fields expected in the CSV are as follows:
2015-12-26 04:42:59 +00:00
+ First Name
+ Last Name
+ Position
+ Email
+ Company
2015-12-26 04:09:32 +00:00
2015-12-26 04:42:59 +00:00
+ Request (multipart/form-data; boundary=----BOUNDARY)
2015-12-26 04:09:32 +00:00
2015-12-26 04:42:59 +00:00
+ Body
------BOUNDARY
Content-Disposition: form-data; name="files[]"; filename="filename.csv"
Content-Type: application/vnd.ms-excel
[File Content]
------BOUNDARY
2015-12-26 04:09:32 +00:00
+ Response 201 (application/json)
2016-01-12 04:29:11 +00:00
+ Attributes (array[Target])
2015-12-26 04:09:32 +00:00
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Email [/import/email]
### Import an Email [POST]
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 (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 (application/json)
+ Attributes (ImportEmailResponse)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
## Site [/import/site]
### Import a Site [POST]
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 (application/json)
+ Attributes (ImportSiteRequest)
+ Response 201 (application/json)
+ Attributes (ImportSiteResponse)
+ Response 400 (application/json)
+ Attributes (BadRequestResponse)
2016-01-06 04:16:21 +00:00
# Data Structures
## Target (object)
+ id: 1 (number, required) - 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
## Group (object)
+ id: 1 (number, required) - 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
2016-01-12 04:29:11 +00:00
+ targets: array[Target] (required) - The targets in the group
2016-01-06 04:16:21 +00:00
## Attachment (object)
+ id: 1 (number, required) - Unique identifier
+ name: Example Attachment (string, required) - Filename of Attachment
+ content: (string, required) - Base64 encoded attachment content
+ type: `text/plain` (string, required) - MIME type of the Attachment
## Template (object)
+ 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
2016-01-12 04:29:11 +00:00
+ attachments: (array[Attachment]) - The attachments sent with the email template
2016-01-06 04:16:21 +00:00
+ modified_date: `2015-01-01T01:02:03.000000Z` (string) - Date the Template was last modified
## Page (object)
+ id: 1 (number, required) - Unique identifier
+ name: Example Page (string, required) - 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
## Result (object)
+ id: 1 (number, required) - Unique identifier
2016-01-12 04:29:11 +00:00
+ email: foo@example.com - The 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.00000 (number) - The latitude of the IP address
+ longitude: 0.00000 (number) - The longitude of the IP address
2016-01-06 04:16:21 +00:00
## Event (object)
+ id: 1 (number, required) - Unique identifier
2016-01-12 04:29:11 +00:00
+ email: foo@example.com (required) - The email address of the target
+ time: `2015-01-01T01:02:03.000000Z` (string) - Date the event was generated
+ message: Campaign Created (string) - The description of the event
2016-01-06 04:16:21 +00:00
2016-03-04 02:44:11 +00:00
## SendingProfile (object)
2016-01-06 04:16:21 +00:00
+ id: 1 (number, required) - Unique identifier
2016-01-12 04:29:11 +00:00
+ host: smtp.example.com:25 (required) - The hostname and port for the SMTP server
+ username: foo (string, required) - The username used for SMTP authentication
+ password: bar (string, required) - The password used for SMTP authentication
+ from_address: John Doe <foo@example.com> (string, required) - The "From" address to spoof
2016-03-04 02:44:11 +00:00
+ ignore_cert_errors: false (boolean) - Whether or not to ignore certificate errors
2016-01-06 04:16:21 +00:00
## Campaign (object)
+ id: 1 (number, required) - Unique identifier
+ name: Example Campaign (required) - Title of Campaign
+ created_date: `2015-01-01T01:02:03.000000Z` (string) - Date the Campaign was created
+ completed_date: `2015-01-01T01:02:03.000000Z` (string) - Date the Campaign was completed
+ template: (Template) (required) - Email template to use in Campaign
2016-01-12 04:29:11 +00:00
+ page: (Page) (required) - Landing page for users who click the phishing link
2016-01-06 04:16:21 +00:00
+ status: Emails Sent (required, string) - The current status of the campaign
2016-01-12 04:29:11 +00:00
+ results: (array[Result]) - The results of the campaign
+ timeline: (array[Event]) - The event timeline
2016-03-04 02:44:11 +00:00
+ smtp: (SendingProfile) - The Sending Profile settings used in the campaign
2016-01-06 04:16:21 +00:00
+ url: http://foo.bar (string, required) - The URL used in the Template sent to users
## ImportSiteRequest (object)
+ url: http://foo.bar (string, required) - The URL to be retrieved
## ImportSiteResponse (object)
+ html: `<html><head></head><body>This is a test message!</body></html>` (string, required) - HTML of the requested URL.
## ImportEmailResponse (object)
+ text: Foo bar (string) - The email text part
+ html: "\u003cdiv\u003eFoo bar\u003c/div\u003e" (string) - The email HTML part
+ subject: Foo Bar (string) - The email subject
## BadRequestResponse (object)
2016-01-12 04:29:11 +00:00
+ message: Error message (string) - The detailed error message
2016-01-06 04:16:21 +00:00
+ success: false (boolean) - The success status of the request
+ data: Any associated data
