# Campaigns

Campaigns have the following structure:

```
{
  id                  : int64
  name                : string
  created_date        : string(datetime)
  launch_date         : string(datetime)
  send_by_date        : string(datetime)
  completed_date      : string(datetime)
  template            : Template
  page                : Page
  status              : string
  results             : []Result
  groups              : []Group
  timeline            : []Event
  smtp                : SMTP
  url                 : string
}
```

The `template`, `page`, `groups`, and `smtp` objects are all Gophish objects. Their format can be found at their various API endpoints.

### Campaign Events

Gophish keeps track of every event for a campaign in it's `timeline`. Each event has the following format:

```
{
  email                : string
  time                 : string(datetime)
  message              : string
  details              : string(JSON)
}
```

The `details` field is a string containing JSON which contains the raw data about an event (such as credentials that were submitted, user-agent information, and more). The `details` field has the following format:

```
{
  payload              : object
  browser              : object
}
```

### Campaign Results

In addition to this, campaign results are maintained in the `results` attribute. This has a format similar to the members of a `Group`, in that they have the following structure:

```
{
  id                   : int64
  first_name           : string
  last_name            : string
  position             : string
  status               : string
  ip                   : string
  latitude             : float
  longitude            : float
  send_date            : string(datetime)
  reported             : boolean
}
```

## Get Campaigns

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/campaigns/`

Returns a list of campaigns.

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "id": 1,
    "name": "Example Campaign",
    "created_date": "2018-10-08T15:56:29.48815Z",
    "launch_date": "2018-10-08T15:56:00Z",
    "send_by_date": "0001-01-01T00:00:00Z",
    "completed_date": "0001-01-01T00:00:00Z",
    "template": {
      "id": 1,
      "name": "Example Template",
      "subject": "Click here!",
      "text": "",
      "html": "\u003chtml\u003e\n\u003chead\u003e\n\t\u003ctitle\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cp\u003eClick \u003ca href=\"{{.URL}}\"\u003ehere\u003c/a\u003e!\u003c/p\u003e\n{{.Tracker}}\u003c/body\u003e\n\u003c/html\u003e\n",
      "modified_date": "2018-10-08T15:54:56.258392Z",
      "attachments": []
    },
    "page": {
      "id": 1,
      "name": "Example Landing Page",
      "html": "\u003chtml\u003e\u003chead\u003e\n\t\u003ctitle\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cp\u003eLanding page HTML\u003c/p\u003e\n\n\n\u003c/body\u003e\u003c/html\u003e",
      "capture_credentials": false,
      "capture_passwords": false,
      "redirect_url": "",
      "modified_date": "2018-10-08T15:55:16.416396Z"
    },
    "status": "In progress",
    "results": [
      {
        "id": "hoqKYFn",
        "status": "Email Sent",
        "ip": "",
        "latitude": 0,
        "longitude": 0,
        "send_date": "2018-10-08T15:56:29.535158Z",
        "reported": false,
        "modified_date": "2018-10-08T15:56:29.535158Z",
        "email": "user@example.com",
        "first_name": "Example",
        "last_name": "User",
        "position": ""
      },
      {
        "id": "VYrDwtG",
        "status": "Clicked Link",
        "ip": "::1",
        "latitude": 0,
        "longitude": 0,
        "send_date": "2018-10-08T15:56:29.548722Z",
        "reported": false,
        "modified_date": "2018-10-08T15:56:46.955281Z",
        "email": "foo@bar.com",
        "first_name": "Foo",
        "last_name": "Bar",
        "position": ""
      }
    ],
    "timeline": [
      {
        "email": "",
        "time": "2018-10-08T15:56:29.49172Z",
        "message": "Campaign Created",
        "details": ""
      },
      {
        "email": "user@example.com",
        "time": "2018-10-08T15:56:29.535158Z",
        "message": "Email Sent",
        "details": ""
      },
      {
        "email": "foo@bar.com",
        "time": "2018-10-08T15:56:29.548722Z",
        "message": "Email Sent",
        "details": ""
      },
      {
        "email": "foo@bar.com",
        "time": "2018-10-08T15:56:44.679743Z",
        "message": "Email Opened",
        "details": "{\"payload\":{\"rid\":[\"VYrDwtG\"]},\"browser\":{\"address\":\"::1\",\"user-agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36\"}}"
      },
      {
        "email": "foo@bar.com",
        "time": "2018-10-08T15:56:46.955281Z",
        "message": "Clicked Link",
        "details": "{\"payload\":{\"rid\":[\"VYrDwtG\"]},\"browser\":{\"address\":\"::1\",\"user-agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36\"}}"
      }
    ],
    "smtp": {
      "id": 1,
      "interface_type": "SMTP",
      "name": "Example Sending Profile",
      "host": "localhost:1025",
      "from_address": "Test User \u003ctest@test.com\u003e",
      "ignore_cert_errors": true,
      "headers": [],
      "modified_date": "2018-09-04T01:24:21.691924069Z"
    },
    "url": "http://localhost"
  }
]
```

{% endtab %}
{% endtabs %}

## Get Campaign

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/campaigns/:id`

Returns a campaign given an ID.

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | The campaign ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1,
  "name": "Example Campaign",
  "created_date": "2018-10-08T15:56:29.48815Z",
  "launch_date": "2018-10-08T15:56:00Z",
  "send_by_date": "0001-01-01T00:00:00Z",
  "completed_date": "0001-01-01T00:00:00Z",
  "template": {
    "id": 1,
    "name": "Example Template",
    "subject": "Click here!",
    "text": "",
    "html": "\u003chtml\u003e\n\u003chead\u003e\n\t\u003ctitle\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cp\u003eClick \u003ca href=\"{{.URL}}\"\u003ehere\u003c/a\u003e!\u003c/p\u003e\n{{.Tracker}}\u003c/body\u003e\n\u003c/html\u003e\n",
    "modified_date": "2018-10-08T15:54:56.258392Z",
    "attachments": []
  },
  "page": {
    "id": 1,
    "name": "Example Landing Page",
    "html": "\u003chtml\u003e\u003chead\u003e\n\t\u003ctitle\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cp\u003eLanding page HTML\u003c/p\u003e\n\n\n\u003c/body\u003e\u003c/html\u003e",
    "capture_credentials": false,
    "capture_passwords": false,
    "redirect_url": "",
    "modified_date": "2018-10-08T15:55:16.416396Z"
  },
  "status": "In progress",
  "results": [
    {
      "id": "hoqKYFn",
      "status": "Email Sent",
      "ip": "",
      "latitude": 0,
      "longitude": 0,
      "send_date": "2018-10-08T15:56:29.535158Z",
      "reported": false,
      "modified_date": "2018-10-08T15:56:29.535158Z",
      "email": "user@example.com",
      "first_name": "Example",
      "last_name": "User",
      "position": ""
    },
    {
      "id": "VYrDwtG",
      "status": "Clicked Link",
      "ip": "::1",
      "latitude": 0,
      "longitude": 0,
      "send_date": "2018-10-08T15:56:29.548722Z",
      "reported": false,
      "modified_date": "2018-10-08T15:56:46.955281Z",
      "email": "foo@bar.com",
      "first_name": "Foo",
      "last_name": "Bar",
      "position": ""
    }
  ],
  "timeline": [
    {
      "email": "",
      "time": "2018-10-08T15:56:29.49172Z",
      "message": "Campaign Created",
      "details": ""
    },
    {
      "email": "user@example.com",
      "time": "2018-10-08T15:56:29.535158Z",
      "message": "Email Sent",
      "details": ""
    },
    {
      "email": "foo@bar.com",
      "time": "2018-10-08T15:56:29.548722Z",
      "message": "Email Sent",
      "details": ""
    },
    {
      "email": "foo@bar.com",
      "time": "2018-10-08T15:56:44.679743Z",
      "message": "Email Opened",
      "details": "{\"payload\":{\"rid\":[\"VYrDwtG\"]},\"browser\":{\"address\":\"::1\",\"user-agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36\"}}"
    },
    {
      "email": "foo@bar.com",
      "time": "2018-10-08T15:56:46.955281Z",
      "message": "Clicked Link",
      "details": "{\"payload\":{\"rid\":[\"VYrDwtG\"]},\"browser\":{\"address\":\"::1\",\"user-agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36\"}}"
    }
  ],
  "smtp": {
    "id": 1,
    "interface_type": "SMTP",
    "name": "Example Sending Profile",
    "host": "localhost:1025",
    "from_address": "Test User \u003ctest@test.com\u003e",
    "ignore_cert_errors": true,
    "headers": [],
    "modified_date": "2018-09-04T01:24:21.691924069Z"
  },
  "url": "http://localhost"
}
```

{% endtab %}

{% tab title="404 " %}

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

{% endtab %}
{% endtabs %}

Returns a 404 error if the specified campaign isn't found.

## Create Campaign

<mark style="color:green;">`POST`</mark> `https://localhost:3333/api/campaigns/`

Creates and launches a new campaign.

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

#### Request Body

| Name    | Type   | Description                                                                    |
| ------- | ------ | ------------------------------------------------------------------------------ |
| Payload | object | The campaign details. See the introduction above for the format of a campaign. |

{% tabs %}
{% tab title="201 " %}

```javascript
{
  "id": 1,
  "name": "Example Campaign",
  "created_date": "2018-10-08T15:56:29.48815Z",
  "launch_date": "2018-10-08T15:56:00Z",
  "send_by_date": "0001-01-01T00:00:00Z",
  "completed_date": "0001-01-01T00:00:00Z",
  "template": {
    "id": 1,
    "name": "Example Template",
    "subject": "Click here!",
    "text": "",
    "html": "\u003chtml\u003e\n\u003chead\u003e\n\t\u003ctitle\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cp\u003eClick \u003ca href=\"{{.URL}}\"\u003ehere\u003c/a\u003e!\u003c/p\u003e\n{{.Tracker}}\u003c/body\u003e\n\u003c/html\u003e\n",
    "modified_date": "2018-10-08T15:54:56.258392Z",
    "attachments": []
  },
  "page": {
    "id": 1,
    "name": "Example Landing Page",
    "html": "\u003chtml\u003e\u003chead\u003e\n\t\u003ctitle\u003e\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cp\u003eLanding page HTML\u003c/p\u003e\n\n\n\u003c/body\u003e\u003c/html\u003e",
    "capture_credentials": false,
    "capture_passwords": false,
    "redirect_url": "",
    "modified_date": "2018-10-08T15:55:16.416396Z"
  },
  "status": "In progress",
  "results": [
    {
      "id": "hoqKYFn",
      "status": "Email Sent",
      "ip": "",
      "latitude": 0,
      "longitude": 0,
      "send_date": "2018-10-08T15:56:29.535158Z",
      "reported": false,
      "modified_date": "2018-10-08T15:56:29.535158Z",
      "email": "user@example.com",
      "first_name": "Example",
      "last_name": "User",
      "position": ""
    },
    {
      "id": "VYrDwtG",
      "status": "Clicked Link",
      "ip": "::1",
      "latitude": 0,
      "longitude": 0,
      "send_date": "2018-10-08T15:56:29.548722Z",
      "reported": false,
      "modified_date": "2018-10-08T15:56:46.955281Z",
      "email": "foo@bar.com",
      "first_name": "Foo",
      "last_name": "Bar",
      "position": ""
    }
  ],
  "timeline": null,
  "smtp": {
    "id": 1,
    "interface_type": "SMTP",
    "name": "Example Sending Profile",
    "host": "localhost:1025",
    "from_address": "Test User \u003ctest@test.com\u003e",
    "ignore_cert_errors": true,
    "headers": [],
    "modified_date": "2018-09-04T01:24:21.691924069Z"
  },
  "url": "http://localhost"
}
```

{% endtab %}
{% endtabs %}

This method expects the campaign to be provided in JSON format. For the various objects in a campaign, such as the template, landing page, or sending profile, you need to provide the `name` attribute. Here's an example of a JSON payload to create a new campaign:

```javascript
{
    "name":"CC Example Campaign",
    "template":{"name":"Example Template"},
    "url":"http://localhost",
    "page":{"name":"Example Landing Page"},
    "smtp":{"name":"Example Sending Profile"},
    "launch_date":"2018-10-08T16:20:00+00:00",
    "send_by_date":null,
    "groups":[{"name":"Example Group"}]
}
```

### Scheduling a Campaign

You can schedule a campaign to launch at a later time. To do this, simply put the desired time you want the campaign to launch in the `launch_date` attribute. Gophish expects the date to be provided in ISO8601 format.

Without setting a launch date, Gophish launches the campaign immediately.

### Spreading out Emails

By default, Gophish sends all the emails in a campaign as quickly as possible. Instead, you may wish to spread emails out over a period of minutes, hours, days, or weeks. This is possible by setting the `send_by_date` to an ISO8601 formatted datetime. It's important to note that this must be after the `launch_date`.

## Get Campaign Results

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/campaigns/:id/results`

Gets the results for a campaign.

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | The campaign ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1,
  "name": "Example Campaign",
  "status": "In progress",
  "results": [
    {
      "id": "hoqKYFn",
      "status": "Email Sent",
      "ip": "",
      "latitude": 0,
      "longitude": 0,
      "send_date": "2018-10-08T15:56:29.535158Z",
      "reported": false,
      "modified_date": "2018-10-08T15:56:29.535158Z",
      "email": "user@example.com",
      "first_name": "Example",
      "last_name": "User",
      "position": ""
    },
    {
      "id": "VYrDwtG",
      "status": "Clicked Link",
      "ip": "::1",
      "latitude": 0,
      "longitude": 0,
      "send_date": "2018-10-08T15:56:29.548722Z",
      "reported": false,
      "modified_date": "2018-10-08T15:56:46.955281Z",
      "email": "foo@bar.com",
      "first_name": "Foo",
      "last_name": "Bar",
      "position": ""
    }
  ],
  "timeline": [
    {
      "email": "",
      "time": "2018-10-08T15:56:29.49172Z",
      "message": "Campaign Created",
      "details": ""
    },
    {
      "email": "user@example.com",
      "time": "2018-10-08T15:56:29.535158Z",
      "message": "Email Sent",
      "details": ""
    },
    {
      "email": "foo@bar.com",
      "time": "2018-10-08T15:56:29.548722Z",
      "message": "Email Sent",
      "details": ""
    },
    {
      "email": "foo@bar.com",
      "time": "2018-10-08T15:56:44.679743Z",
      "message": "Email Opened",
      "details": "{\"payload\":{\"rid\":[\"VYrDwtG\"]},\"browser\":{\"address\":\"::1\",\"user-agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36\"}}"
    },
    {
      "email": "foo@bar.com",
      "time": "2018-10-08T15:56:46.955281Z",
      "message": "Clicked Link",
      "details": "{\"payload\":{\"rid\":[\"VYrDwtG\"]},\"browser\":{\"address\":\"::1\",\"user-agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36\"}}"
    }
  ]
}
```

{% endtab %}

{% tab title="404 " %}

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

{% endtab %}
{% endtabs %}

You may not always want the full campaign details, including the template, landing page, etc. Instead, you may just want to poll the campaign results for updates. This API endpoint only returns information that's relevant to the campaign results.

Returns a 404 error if the specified campaign isn't found.

## Get Campaign Summary

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/campaigns/:id/summary`

Returns summary information about a campaign.

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | The campaign ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1,
  "created_date": "2018-10-08T15:56:29.48815Z",
  "launch_date": "2018-10-08T15:56:00Z",
  "send_by_date": "0001-01-01T00:00:00Z",
  "completed_date": "0001-01-01T00:00:00Z",
  "status": "In progress",
  "name": "Example Campaign",
  "stats": {
    "total": 2,
    "sent": 2,
    "opened": 1,
    "clicked": 1,
    "submitted_data": 0,
    "email_reported": 0,
    "error": 0
  }
}
```

{% endtab %}

{% tab title="404 " %}

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

{% endtab %}
{% endtabs %}

Returns a 404 error if the specified campaign isn't found.

There may be cases where you aren't interested in the specific results, but rather want high-level statistics, or a "summary", about a campaign.

The response includes a `stats` object which has the following format:

```
{
  total            : int
  sent             : int
  opened           : int
  clicked          : int
  submitted_data   : int
  email_reported   : int
}
```

## Delete Campaign

<mark style="color:red;">`DELETE`</mark> `https://localhost:3333/api/campaigns/:id`

Deletes a campaign by ID.

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | The campaign ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "message": "Campaign deleted successfully!",
  "success": true,
  "data": null
}
```

{% endtab %}

{% tab title="404 " %}

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

{% endtab %}
{% endtabs %}

Returns a 404 error if the specified campaign isn't found.

## Complete Campaign

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/campaigns/:id/complete`

Marks a campaign as complete.

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | The campaign ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "message": "Campaign completed successfully!",
  "success": true,
  "data": null
}
```

{% endtab %}
{% endtabs %}