Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

Monitor Records

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 a subuser 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

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

{
  "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

<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

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

{
  "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

<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

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

{
  "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

<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

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

[
  {
    "name": "sampleNameA",
    "email": "example@example.com",
    "frequency": "1000",
    "users": [

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

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

<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>exampexample@example.comom</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

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

{
  "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

<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

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

{
  "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

<result>
   <message>success</message>
</result>
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more