Subversion Repositories cheapmusic

This documentation is based on our [OAI specification](https://github.com/sendgrid/sendgrid-oai).

# INITIALIZATION

```php

// If you are using Composer

require 'vendor/autoload.php';

$apiKey = getenv('SENDGRID_API_KEY');

$sg = new \SendGrid($apiKey);

```

# Table of Contents

* [ACCESS SETTINGS](#access_settings)

* [ALERTS](#alerts)

* [API KEYS](#api_keys)

* [ASM](#asm)

* [BROWSERS](#browsers)

* [CAMPAIGNS](#campaigns)

* [CATEGORIES](#categories)

* [CLIENTS](#clients)

* [CONTACTDB](#contactdb)

* [DEVICES](#devices)

* [GEO](#geo)

* [IPS](#ips)

* [MAIL](#mail)

* [MAIL SETTINGS](#mail_settings)

* [MAILBOX PROVIDERS](#mailbox_providers)

* [PARTNER SETTINGS](#partner_settings)

* [SCOPES](#scopes)

* [SENDERS](#senders)

* [STATS](#stats)

* [SUBUSERS](#subusers)

* [SUPPRESSION](#suppression)

* [TEMPLATES](#templates)

* [TRACKING SETTINGS](#tracking_settings)

* [USER](#user)

* [WHITELABEL](#whitelabel)

<a name="access_settings"></a>

# ACCESS SETTINGS

## Retrieve all recent access attempts

**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**

IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).

### GET /access_settings/activity

```php

$query_params = json_decode('{"limit": 1}');

$response = $sg->client->access_settings()->activity()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Add one or more IPs to the whitelist

**This endpoint allows you to add one or more IP addresses to your IP whitelist.**

When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once.

IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).

### POST /access_settings/whitelist

```php

$request_body = json_decode('{

  "ips": [

    {

      "ip": "192.168.1.1"

    },

    {

      "ip": "192.*.*.*"

    },

    {

      "ip": "192.168.1.3/32"

    }

  ]

}');

$response = $sg->client->access_settings()->whitelist()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve a list of currently whitelisted IPs

**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**

IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).

### GET /access_settings/whitelist

```php

$response = $sg->client->access_settings()->whitelist()->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Remove one or more IPs from the whitelist

**This endpoint allows you to remove one or more IPs from your IP whitelist.**

You can remove one IP at a time, or you can remove multiple IP addresses.

IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).

### DELETE /access_settings/whitelist

```php

$request_body = json_decode('{

  "ids": [

    1,

    2,

    3

  ]

}');

$response = $sg->client->access_settings()->whitelist()->delete($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve a specific whitelisted IP

**This endpoint allows you to retreive a specific IP address that has been whitelisted.**

You must include the ID for the specific IP address you want to retrieve in your call.

IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).

### GET /access_settings/whitelist/{rule_id}

```php

$rule_id = "test_url_param";

$response = $sg->client->access_settings()->whitelist()->_($rule_id)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Remove a specific IP from the whitelist

**This endpoint allows you to remove a specific IP address from your IP whitelist.**

When removing a specific IP address from your whitelist, you must include the ID in your call.

IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.

For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).

### DELETE /access_settings/whitelist/{rule_id}

```php

$rule_id = "test_url_param";

$response = $sg->client->access_settings()->whitelist()->_($rule_id)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

<a name="alerts"></a>

# ALERTS

## Create a new Alert

**This endpoint allows you to create a new alert.**

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.

* Usage alerts allow you to set the threshold at which an alert will be sent.

* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".

For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).

### POST /alerts

```php

$request_body = json_decode('{

  "email_to": "example@example.com",

  "frequency": "daily",

  "type": "stats_notification"

}');

$response = $sg->client->alerts()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve all alerts

**This endpoint allows you to retieve all of your alerts.**

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.

* Usage alerts allow you to set the threshold at which an alert will be sent.

* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".

For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).

### GET /alerts

```php

$response = $sg->client->alerts()->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Update an alert

**This endpoint allows you to update an alert.**

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.

* Usage alerts allow you to set the threshold at which an alert will be sent.

* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".

For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).

### PATCH /alerts/{alert_id}

```php

$request_body = json_decode('{

  "email_to": "example@example.com"

}');

$alert_id = "test_url_param";

$response = $sg->client->alerts()->_($alert_id)->patch($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve a specific alert

**This endpoint allows you to retrieve a specific alert.**

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.

* Usage alerts allow you to set the threshold at which an alert will be sent.

* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".

For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).

### GET /alerts/{alert_id}

```php

$alert_id = "test_url_param";

$response = $sg->client->alerts()->_($alert_id)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Delete an alert

**This endpoint allows you to delete an alert.**

Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.

* Usage alerts allow you to set the threshold at which an alert will be sent.

* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly".

For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).

### DELETE /alerts/{alert_id}

```php

$alert_id = "test_url_param";

$response = $sg->client->alerts()->_($alert_id)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

<a name="api_keys"></a>

# API KEYS

## Create API keys

**This enpoint allows you to create a new random API Key for the user.**

A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned.

There is a limit of 100 API Keys on your account.

The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).

See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.

### POST /api_keys

```php

$request_body = json_decode('{

  "name": "My API Key",

  "sample": "data",

  "scopes": [

    "mail.send",

    "alerts.create",

    "alerts.read"

  ]

}');

$response = $sg->client->api_keys()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve all API Keys belonging to the authenticated user

**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**

The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).

### GET /api_keys

```php

$query_params = json_decode('{"limit": 1}');

$response = $sg->client->api_keys()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Update the name & scopes of an API Key

**This endpoint allows you to update the name and scopes of a given API key.**

A JSON request body with a "name" property is required.

Most provide the list of all the scopes an api key should have.

The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).

### PUT /api_keys/{api_key_id}

```php

$request_body = json_decode('{

  "name": "A New Hope",

  "scopes": [

    "user.profile.read",

    "user.profile.update"

  ]

}');

$api_key_id = "test_url_param";

$response = $sg->client->api_keys()->_($api_key_id)->put($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Update API keys

**This endpoint allows you to update the name of an existing API Key.**

A JSON request body with a "name" property is required.

The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).

## URI Parameters

| URI Parameter   | Type  | Required?  | Description  |

|---|---|---|---|

|api_key_id |string | required | The ID of the API Key you are updating.|

### PATCH /api_keys/{api_key_id}

```php

$request_body = json_decode('{

  "name": "A New Hope"

}');

$api_key_id = "test_url_param";

$response = $sg->client->api_keys()->_($api_key_id)->patch($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve an existing API Key

**This endpoint allows you to retrieve a single api key.**

If the API Key ID does not exist an HTTP 404 will be returned.

### GET /api_keys/{api_key_id}

```php

$api_key_id = "test_url_param";

$response = $sg->client->api_keys()->_($api_key_id)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Delete API keys

**This endpoint allows you to revoke an existing API Key**

Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.

The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).

## URI Parameters

| URI Parameter   | Type  | Required?  | Description  |

|---|---|---|---|

|api_key_id |string | required | The ID of the API Key you are deleting.|

### DELETE /api_keys/{api_key_id}

```php

$api_key_id = "test_url_param";

$response = $sg->client->api_keys()->_($api_key_id)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

<a name="asm"></a>

# ASM

## Create a new suppression group

**This endpoint allows you to create a new suppression group.**

Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.

The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.

Each user can create up to 25 different suppression groups.

### POST /asm/groups

```php

$request_body = json_decode('{

  "description": "Suggestions for products our users might like.",

  "is_default": true,

  "name": "Product Suggestions"

}');

$response = $sg->client->asm()->groups()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve information about multiple suppression groups

**This endpoint allows you to retrieve information about multiple suppression groups.**

This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.

Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).

Suppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content.

### GET /asm/groups

```php

$query_params = json_decode('{"id": 1}');

$response = $sg->client->asm()->groups()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Update a suppression group.

**This endpoint allows you to update or change a suppression group.**

Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.

The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.

Each user can create up to 25 different suppression groups.

### PATCH /asm/groups/{group_id}

```php

$request_body = json_decode('{

  "description": "Suggestions for items our users might like.",

  "id": 103,

  "name": "Item Suggestions"

}');

$group_id = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->patch($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Get information on a single suppression group.

**This endpoint allows you to retrieve a single suppression group.**

Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.

The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.

Each user can create up to 25 different suppression groups.

### GET /asm/groups/{group_id}

```php

$group_id = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Delete a suppression group.

**This endpoint allows you to delete a suppression group.**

You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list.

Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.

The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.

Each user can create up to 25 different suppression groups.

### DELETE /asm/groups/{group_id}

```php

$group_id = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Add suppressions to a suppression group

**This endpoint allows you to add email addresses to an unsubscribe group.**

If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.

Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.

### POST /asm/groups/{group_id}/suppressions

```php

$request_body = json_decode('{

  "recipient_emails": [

    "test1@example.com",

    "test2@example.com"

  ]

}');

$group_id = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve all suppressions for a suppression group

**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**

Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.

### GET /asm/groups/{group_id}/suppressions

```php

$group_id = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Search for suppressions within a group

**This endpoint allows you to search a suppression group for multiple suppressions.**

When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.

Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).

### POST /asm/groups/{group_id}/suppressions/search

```php

$request_body = json_decode('{

  "recipient_emails": [

    "exists1@example.com",

    "exists2@example.com",

    "doesnotexists@example.com"

  ]

}');

$group_id = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->search()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Delete a suppression from a suppression group

**This endpoint allows you to remove a suppressed email address from the given suppression group.**

Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.

### DELETE /asm/groups/{group_id}/suppressions/{email}

```php

$group_id = "test_url_param";

$email = "test_url_param";

$response = $sg->client->asm()->groups()->_($group_id)->suppressions()->_($email)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve all suppressions

**This endpoint allows you to retrieve a list of all suppressions.**

Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).

### GET /asm/suppressions

```php

$response = $sg->client->asm()->suppressions()->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Add recipient addresses to the global suppression group.

**This endpoint allows you to add one or more email addresses to the global suppressions group.**

A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).

### POST /asm/suppressions/global

```php

$request_body = json_decode('{

  "recipient_emails": [

    "test1@example.com",

    "test2@example.com"

  ]

}');

$response = $sg->client->asm()->suppressions()->global()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve a Global Suppression

**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**

If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.

A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).

### GET /asm/suppressions/global/{email}

```php

$email = "test_url_param";

$response = $sg->client->asm()->suppressions()->global()->_($email)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Delete a Global Suppression

**This endpoint allows you to remove an email address from the global suppressions group.**

A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).

### DELETE /asm/suppressions/global/{email}

```php

$email = "test_url_param";

$response = $sg->client->asm()->suppressions()->global()->_($email)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve all suppression groups for an email address

**This endpoint returns the list of all groups that the given email address has been unsubscribed from.**

Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).

### GET /asm/suppressions/{email}

```php

$email = "test_url_param";

$response = $sg->client->asm()->suppressions()->_($email)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

<a name="browsers"></a>

# BROWSERS

## Retrieve email statistics by browser.

**This endpoint allows you to retrieve your email statistics segmented by browser type.**

**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.

Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).

### GET /browsers/stats

```php

$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "browsers": "test_string", "limit": "test_string", "offset": "test_string", "start_date": "2016-01-01"}');

$response = $sg->client->browsers()->stats()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

<a name="campaigns"></a>

# CAMPAIGNS

## Create a Campaign

**This endpoint allows you to create a campaign.**

Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.

Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### POST /campaigns

```php

$request_body = json_decode('{

  "categories": [

    "spring line"

  ],

  "custom_unsubscribe_url": "",

  "html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",

  "ip_pool": "marketing",

  "list_ids": [

    110,

    124

  ],

  "plain_content": "Check out our spring line!",

  "segment_ids": [

    110

  ],

  "sender_id": 124451,

  "subject": "New Products for Spring!",

  "suppression_group_id": 42,

  "title": "March Newsletter"

}');

$response = $sg->client->campaigns()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve all Campaigns

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

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

Returns an empty array if no campaigns exist.

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### GET /campaigns

```php

$query_params = json_decode('{"limit": 1, "offset": 1}');

$response = $sg->client->campaigns()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Update a Campaign

Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters.

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### PATCH /campaigns/{campaign_id}

```php

$request_body = json_decode('{

  "categories": [

    "summer line"

  ],

  "html_content": "<html><head><title></title></head><body><p>Check out our summer line!</p></body></html>",

  "plain_content": "Check out our summer line!",

  "subject": "New Products for Summer!",

  "title": "May Newsletter"

}');

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->patch($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve a single campaign

**This endpoint allows you to retrieve a specific campaign.**

Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### GET /campaigns/{campaign_id}

```php

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Delete a Campaign

**This endpoint allows you to delete a specific campaign.**

Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### DELETE /campaigns/{campaign_id}

```php

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Update a Scheduled Campaign

**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### PATCH /campaigns/{campaign_id}/schedules

```php

$request_body = json_decode('{

  "send_at": 1489451436

}');

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->schedules()->patch($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Schedule a Campaign

**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### POST /campaigns/{campaign_id}/schedules

```php

$request_body = json_decode('{

  "send_at": 1489771528

}');

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->schedules()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## View Scheduled Time of a Campaign

**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### GET /campaigns/{campaign_id}/schedules

```php

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->schedules()->get();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Unschedule a Scheduled Campaign

**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**

A successful unschedule will return a 204.

If the specified campaign is in the process of being sent, the only option is to cancel (a different method).

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### DELETE /campaigns/{campaign_id}/schedules

```php

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->schedules()->delete();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Send a Campaign

**This endpoint allows you to immediately send a campaign at the time you make the API call.**

Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### POST /campaigns/{campaign_id}/schedules/now

```php

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->schedules()->now()->post();

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Send a Test Campaign

**This endpoint allows you to send a test campaign.**

To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]

For more information:

* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)

### POST /campaigns/{campaign_id}/schedules/test

```php

$request_body = json_decode('{

  "to": "your.email@example.com"

}');

$campaign_id = "test_url_param";

$response = $sg->client->campaigns()->_($campaign_id)->schedules()->test()->post($request_body);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

<a name="categories"></a>

# CATEGORIES

## Retrieve all categories

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

Categories can help organize your email analytics by enabling you to tag emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).

### GET /categories

```php

$query_params = json_decode('{"category": "test_string", "limit": 1, "offset": 1}');

$response = $sg->client->categories()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();

```

## Retrieve Email Statistics for Categories

**This endpoint allows you to retrieve all of your email statistics for each of your categories.**

If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.

Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).

### GET /categories/stats

```php

$query_params = json_decode('{"end_date": "2016-04-01", "aggregated_by": "day", "limit": 1, "offset": 1, "start_date": "2016-01-01", "categories": "test_string"}');

$response = $sg->client->categories()->stats()->get(null, $query_params);

echo $response->statusCode();

echo $response->body();

echo $response->headers();