# Retrieve all Campaigns

## API Overview

> \[!WARNING]
>
> This covers the obsolete Legacy Marketing Campaigns API.

> \[!NOTE]
>
> For the most up-to-date information on the Sender Identities API, please visit the [new Marketing Campaigns Single Sends API](/docs/sendgrid/api-reference/single-sends).

The Campaigns API allows you to create and manage marketing campaigns. You can create campaigns, manage campaign content, and schedule campaigns to be sent at a later time.

## Operation overview

```json
{"path":"https://api.sendgrid.com/v3/campaigns","method":"get","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]}
```

**This endpoint allows you to retrieve a paginated list of all of your campaigns.**

Returns campaigns in reverse order they were created (newest first).

Returns an empty array if no campaigns exist.

You can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.

## Operation details

### Authentication

API Key

### Headers

```json
[{"in":"header","name":"Authorization","required":true,"default":"Bearer <<YOUR_API_KEY_HERE>>","schema":{"type":"string"}},{"name":"on-behalf-of","in":"header","description":"The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id <account-id>`). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: <subuser-username>`). See [**On Behalf Of**](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.","required":false,"schema":{"type":"string"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}]
```

### Query string

```json
[{"name":"limit","in":"query","description":"`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used.","schema":{"type":"integer","minimum":1,"default":10}},{"name":"offset","in":"query","required":false,"description":"The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.","schema":{"type":"integer","minimum":0,"default":0},"refName":"#/components/parameters/PaginationCommonOffset","modelName":"__components_parameters_PaginationCommonOffset"}]
```

### Responses

```json
[{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"array","items":{"title":"Campaigns Response","type":"object","required":["status","title"],"refName":"Campaigns2xx","modelName":"Campaigns2xx","properties":{"title":{"type":"string","description":"The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI."},"subject":{"description":"The subject of your campaign that your recipients will see.","nullable":true,"type":"string"},"sender_id":{"description":"The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails.","nullable":true,"type":"integer"},"list_ids":{"description":"The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs","nullable":true,"type":"array","items":{"type":"integer"}},"segment_ids":{"description":"The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. Segments are limited to 10 segment IDs.","nullable":true,"type":"array","items":{"type":"integer"}},"categories":{"description":"The categories you would like associated to this campaign.","nullable":true,"type":"array","items":{"type":"string"}},"suppression_group_id":{"description":"The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.","nullable":true,"type":"integer"},"custom_unsubscribe_url":{"description":"This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.","nullable":true,"type":"string"},"ip_pool":{"description":"The pool of IPs that you would like to send this email from.","nullable":true,"type":"string"},"html_content":{"description":"The HTML of your marketing email.","nullable":true,"type":"string"},"plain_content":{"description":"The plain text content of your emails.","nullable":true,"type":"string"},"editor":{"type":"string","description":"The editor used in the UI.","enum":["code","design"],"refName":"Editor","modelName":"Editor"},"status":{"type":"string","description":"The status of your campaign."},"id":{"type":"integer"}}}}}},"examples":{"response":{"value":{"result":[{"id":986724,"title":"March Newsletter","subject":"New Products for Spring!","sender_id":124451,"list_ids":[110,124],"segment_ids":[110],"categories":["spring line"],"suppression_group_id":42,"custom_unsubscribe_url":"","ip_pool":"marketing","html_content":"<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>","plain_content":"Check out our spring line!","status":"Draft"},{"id":986723,"title":"February Newsletter","subject":"Final Winter Product Sale!","sender_id":124451,"list_ids":[110,124],"segment_ids":[110],"categories":["winter line"],"suppression_group_id":42,"custom_unsubscribe_url":"","ip_pool":"marketing","html_content":"<html><head><title></title></head><body><p>Last call for winter clothes!</p></body></html>","plain_content":"Last call for winter clothes!","status":"Sent"}]}}}}}}}]
```

## Retrieving paginated results

To perform a request for the first page of the paginated list of all campaigns using the default page size, you can omit the `limit` and `offset` query parameters:

Retrieve first page from list of all campaigns

```js
const client = require("@sendgrid/client");
client.setApiKey(process.env.SENDGRID_API_KEY);

const queryParams = { limit: 10 };

const request = {
  url: `/v3/campaigns`,
  method: "GET",
  qs: queryParams,
};

client
  .request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch((error) => {
    console.error(error);
  });
```

```python
import os
from sendgrid import SendGridAPIClient


sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY"))

params = {"limit": 10}

response = sg.client.campaigns.get(query_params=params)

print(response.status_code)
print(response.body)
print(response.headers)
```

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SendGrid;

public class Program {
    public static async Task Main() {
        string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);

        var queryParams = @"{'limit': 10}";

        var response = await client.RequestAsync(
            method: SendGridClient.Method.GET, urlPath: "campaigns", queryParams: queryParams);

        Console.WriteLine(response.StatusCode);
        Console.WriteLine(response.Body.ReadAsStringAsync().Result);
        Console.WriteLine(response.Headers.ToString());
    }
}
```

```java
import com.sendgrid.*;
import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException {
        try {
            SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
            Request request = new Request();
            request.setMethod(Method.GET);
            request.setEndpoint("/campaigns");
            request.addQueryParam("limit", "10");
            Response response = sg.api(request);
            System.out.println(response.getStatusCode());
            System.out.println(response.getBody());
            System.out.println(response.getHeaders());
        } catch (IOException ex) {
            throw ex;
        }
    }
}
```

```go
package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
	"os"
)

func main() {
	apiKey := os.Getenv("SENDGRID_API_KEY")
	host := "https://api.sendgrid.com"
	request := sendgrid.GetRequest(apiKey, "/v3/campaigns", host)
	request.Method = "GET"
	queryParams := make(map[string]string)
	queryParams["limit"] = "10"
	request.QueryParams = queryParams
	response, err := sendgrid.API(request)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}
```

```php
<?php
// Uncomment the next line if you're using a dependency loader (such as Composer) (recommended)
// require 'vendor/autoload.php';

// Uncomment next line if you're not using a dependency loader (such as Composer)
// require_once '<PATH TO>/sendgrid-php.php';

$apiKey = getenv("SENDGRID_API_KEY");
$sg = new \SendGrid($apiKey);
$query_params = json_decode('{
    "limit": 10
}');

try {
    $response = $sg->client->campaigns()->get(null, $query_params);
    print $response->statusCode() . "\n";
    print_r($response->headers());
    print $response->body() . "\n";
} catch (Exception $ex) {
    echo "Caught exception: " . $ex->getMessage();
}
```

```ruby
require 'sendgrid-ruby'
include SendGrid

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
params = JSON.parse('{
  "limit": 10
}')

response = sg.client.campaigns.get(query_params: params)
puts response.status_code
puts response.headers
puts response.body
```

```bash
curl -G -X GET "https://api.sendgrid.com/v3/campaigns?limit=10" \
--header "Authorization: Bearer $SENDGRID_API_KEY"
```

If you want to specify a page size of your choice, you can use the `limit` query parameter. Assume you want a page size of no more than 5 items per request, to retrieve the first page you can use the `limit` parameter without specifying an `offset`:

Retrieve first page from list of all campaigns with a specified page size

```js
const client = require("@sendgrid/client");
client.setApiKey(process.env.SENDGRID_API_KEY);

const queryParams = { limit: 5 };

const request = {
  url: `/v3/campaigns`,
  method: "GET",
  qs: queryParams,
};

client
  .request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch((error) => {
    console.error(error);
  });
```

```python
import os
from sendgrid import SendGridAPIClient


sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY"))

params = {"limit": 5}

response = sg.client.campaigns.get(query_params=params)

print(response.status_code)
print(response.body)
print(response.headers)
```

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SendGrid;

public class Program {
    public static async Task Main() {
        string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);

        var queryParams = @"{'limit': 5}";

        var response = await client.RequestAsync(
            method: SendGridClient.Method.GET, urlPath: "campaigns", queryParams: queryParams);

        Console.WriteLine(response.StatusCode);
        Console.WriteLine(response.Body.ReadAsStringAsync().Result);
        Console.WriteLine(response.Headers.ToString());
    }
}
```

```java
import com.sendgrid.*;
import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException {
        try {
            SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
            Request request = new Request();
            request.setMethod(Method.GET);
            request.setEndpoint("/campaigns");
            request.addQueryParam("limit", "5");
            Response response = sg.api(request);
            System.out.println(response.getStatusCode());
            System.out.println(response.getBody());
            System.out.println(response.getHeaders());
        } catch (IOException ex) {
            throw ex;
        }
    }
}
```

```go
package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
	"os"
)

func main() {
	apiKey := os.Getenv("SENDGRID_API_KEY")
	host := "https://api.sendgrid.com"
	request := sendgrid.GetRequest(apiKey, "/v3/campaigns", host)
	request.Method = "GET"
	queryParams := make(map[string]string)
	queryParams["limit"] = "5"
	request.QueryParams = queryParams
	response, err := sendgrid.API(request)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}
```

```php
<?php
// Uncomment the next line if you're using a dependency loader (such as Composer) (recommended)
// require 'vendor/autoload.php';

// Uncomment next line if you're not using a dependency loader (such as Composer)
// require_once '<PATH TO>/sendgrid-php.php';

$apiKey = getenv("SENDGRID_API_KEY");
$sg = new \SendGrid($apiKey);
$query_params = json_decode('{
    "limit": 5
}');

try {
    $response = $sg->client->campaigns()->get(null, $query_params);
    print $response->statusCode() . "\n";
    print_r($response->headers());
    print $response->body() . "\n";
} catch (Exception $ex) {
    echo "Caught exception: " . $ex->getMessage();
}
```

```ruby
require 'sendgrid-ruby'
include SendGrid

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
params = JSON.parse('{
  "limit": 5
}')

response = sg.client.campaigns.get(query_params: params)
puts response.status_code
puts response.headers
puts response.body
```

```bash
curl -G -X GET "https://api.sendgrid.com/v3/campaigns?limit=5" \
--header "Authorization: Bearer $SENDGRID_API_KEY"
```

If you want to retrieve items beyond the first page, you can use the `offset` parameter as follows. Assume you are still working with a page size of 5 as determined by your `limit` query parameter and you have more than 15 items. To request the fourth page of items, you can use the `offset` parameter to skip over the first 15 items, i.e. you start retrieving items starting after the first three pages of 5 items each:

Retrieve a specific page from the list of all campaigns

```js
const client = require("@sendgrid/client");
client.setApiKey(process.env.SENDGRID_API_KEY);

const queryParams = {
  limit: 5,
  offset: 15,
};

const request = {
  url: `/v3/campaigns`,
  method: "GET",
  qs: queryParams,
};

client
  .request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch((error) => {
    console.error(error);
  });
```

```python
import os
from sendgrid import SendGridAPIClient


sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY"))

params = {"limit": 5, "offset": 15}

response = sg.client.campaigns.get(query_params=params)

print(response.status_code)
print(response.body)
print(response.headers)
```

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SendGrid;

public class Program {
    public static async Task Main() {
        string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);

        var queryParams = @"{'limit': 5, 'offset': 15}";

        var response = await client.RequestAsync(
            method: SendGridClient.Method.GET, urlPath: "campaigns", queryParams: queryParams);

        Console.WriteLine(response.StatusCode);
        Console.WriteLine(response.Body.ReadAsStringAsync().Result);
        Console.WriteLine(response.Headers.ToString());
    }
}
```

```java
import com.sendgrid.*;
import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException {
        try {
            SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
            Request request = new Request();
            request.setMethod(Method.GET);
            request.setEndpoint("/campaigns");
            request.addQueryParam("limit", "5");
            request.addQueryParam("offset", "15");
            Response response = sg.api(request);
            System.out.println(response.getStatusCode());
            System.out.println(response.getBody());
            System.out.println(response.getHeaders());
        } catch (IOException ex) {
            throw ex;
        }
    }
}
```

```go
package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
	"os"
)

func main() {
	apiKey := os.Getenv("SENDGRID_API_KEY")
	host := "https://api.sendgrid.com"
	request := sendgrid.GetRequest(apiKey, "/v3/campaigns", host)
	request.Method = "GET"
	queryParams := make(map[string]string)
	queryParams["limit"] = "5"
	queryParams["offset"] = "15"
	request.QueryParams = queryParams
	response, err := sendgrid.API(request)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}
```

```php
<?php
// Uncomment the next line if you're using a dependency loader (such as Composer) (recommended)
// require 'vendor/autoload.php';

// Uncomment next line if you're not using a dependency loader (such as Composer)
// require_once '<PATH TO>/sendgrid-php.php';

$apiKey = getenv("SENDGRID_API_KEY");
$sg = new \SendGrid($apiKey);
$query_params = json_decode('{
    "limit": 5,
    "offset": 15
}');

try {
    $response = $sg->client->campaigns()->get(null, $query_params);
    print $response->statusCode() . "\n";
    print_r($response->headers());
    print $response->body() . "\n";
} catch (Exception $ex) {
    echo "Caught exception: " . $ex->getMessage();
}
```

```ruby
require 'sendgrid-ruby'
include SendGrid

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
params = JSON.parse('{
  "limit": 5,
  "offset": 15
}')

response = sg.client.campaigns.get(query_params: params)
puts response.status_code
puts response.headers
puts response.body
```

```bash
curl -G -X GET "https://api.sendgrid.com/v3/campaigns?limit=5&offset=15" \
--header "Authorization: Bearer $SENDGRID_API_KEY"
```