Monitor records will send samples from one or more subusers at a frequency you set.

The first step is to create a Monitor Record. Once the monitor record has been created, you can append asubuser to a monitor record. Multiple subusers can be appended to a single monitor record.

Create Monitor Record

Create a new monitor record on the account.

URI Parameter Required Requirements Description
task Yes Must be set to create Task to create a monitor record
name Yes Must be unique to account. Can not be more than 255 characters Unique name to identify this monitor record
email Yes Must be in email format Email destination to send the sample to
frequency Yes Unsigned integer Interval of emails between samples
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=create&name=myMonitor&email=example@example.com&frequency=1000

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=create&name=myMonitor&email=example@example.com&frequency=1000

Response

1
2
3
<result>
   <message>success</message>
</result>

Edit Monitor Record

Edit an existing Monitor record.

URI Parameter Required Requirements Description
task Yes Must be set to edit Task to edit a monitor record
name Yes Existing monitor record name The monitor record we are going to edit
new_name No Must be unique to account. Can not be more than 255 characters New monitor record name
new_email No Must be in email format The new email destination to send the email sample to
new_frequency No Unsigned integer The new intervals of emails between samples
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=edit&name=myMonitor&new_name=updatedMonitor&new_email=example@example.com&new_frequency=100

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=edit&name=myMonitor&new_name=updatedMonitor&new_email=example@example.com&new_frequency=100

Response

1
2
3
<result>
   <message>success</message>
</result>

Delete Monitor Record

Deleting a monitor record will remove it from SendGrid’s system. Only monitor records with no subusers attached can be deleted.

URI Parameter Required Requirements Description
task Yes Must be set to delete Task to remove a monitor record
name Yes An existing monitor record The unique name to identify this monitor record
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=delete&name=recordToDelete

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=delete&name=recordToDelete

Response

1
2
3
<result>
   <message>success</message>
</result>

List All Monitor Records

List all available monitor records on your account.

URI Parameter Required Requirements Description
task Yes Must be set to list Task to list all monitor records
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=list

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "name": "sampleNameA",
    "email": "example@example.com",
    "frequency": "1000",
    "users": [

    ]
  },
  {
    "name": "sampleNameB",
    "email": "example@example.com",
    "frequency": "10000",
    "users": [
      "user1@example.com",
      "user2@example.com"
    ]
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=list

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<monitors>
   <monitor>
      <name>sampleNameA</name>
      <email>example@example.com</email>
      <frequency>1000</frequency>
      <users/>
   </monitor>
   <monitor>
      <name>sampleNameB</name>
      <email>example@example.com</email>
      <frequency>10000</frequency>
      <users>
         <user>user1@example.com</user>
         <user>user2@example.com</user>
      </users>
   </monitor>
</monitors>

Append a Subuser to a Monitor Record

Append a subuser to an existing monitor record.

URI Parameter Required Requirements Description
task Yes Must be set to append Task to append a monitor record to a subuser
user Yes Subuser must be under your account Subuser we will append a monitor record to
name Yes Must be a valid existing monitor record The name of the monitor record we will be adding the subuser to
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=append&name=myMonitor&user=example@example.com

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=append&name=myMonitor&user=example@example.com

Response

1
2
3
<result>
   <message>success</message>
</result>

Detach A Monitor Record From A Subuser

Detach a subuser from a monitor record.

URI Parameter Required Requirements Description
task Yes Must be set to detach Task required to detach a monitor record from a subuser
user Yes Subuser must be under your account The subuser being removed from the monitor record
name No Must be a valid existing monitor record The name of the monitor record we will be removing the subuser from. If not provided, subuser will be removed from all monitor records
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=detach&user=example@example.com

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.monitor.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=detach&user=example@example.com

Response

1
2
3
<result>
   <message>success</message>
</result>