Skip to content Skip to navigation Skip to topbar

Twilio SendGrid Docs

SendGrid v3 API Documentation

Getting Started

How to use the SendGrid V3 API

Authentication Authorization Errors On Behalf Of Rate Limits Requests Responses

Mail Send

Mail Send API Overview Mail Send Errors

Cancel scheduled sends

Cancel Schedule Sends API Overview Create a batch ID Validate batch ID Retrieve scheduled send Retrieve all scheduled sends Update a scheduled send Cancel or pause a scheduled send Delete a cancellation or pause from a scheduled send

Account Provisioning API

Account Provisioning API Overview

Account

Account API Overview Create Account List Accounts Single Sign-On Delete Account

Account State

Account State API Overview Get Account State Update Account State

Offering

Account Offerings API Overview Get Account Offerings List Offerings Update Account Offerings

Deliverability

Domain Authentication

Domain Authenticate API Overview Authenticate a domain Get the default authentication Retrieve an authenticated domain List all authenticated domains Add an IP to an authenticated domain Remove an IP from an authenticated domain.Validate a domain authentication.Update an authenticated domain Delete an authenticated domain.List the authenticated domain associated with a subuser List the authenticated domains for subusers with multiple associated domains Associate an authenticated domain with a subuser Associate an authenticated domain with a subuser (up to five domains)Disassociate an authenticated domain from a subuser Disassociate an authenticated domain from a subuser with multiple domains

E-Mail Address Validation

Email Address Validation API Overview Validate an email Request Bulk Email Address Validation Upload URL Get Bulk Email Address Validation Jobs Get a Bulk Email Address Validation Job by ID

E-Mail CNAME Records

Email DNS Records Overview Email DNS records to a co-worker

IP Address

IP Address API Overview Add IPs Get remaining IPs count Retrieve all assigned IPs Retrieve all IP addresses Retrieve all IP pools an IP address belongs to

IP Address Management API

IP Address Management API Overview Add a Twilio SendGrid IP Address Get Details for an IP Address Get a List of all IP Addresses on your Account Update Details for an IP Address Create an IP Pool with a Name and IP Assignments Get Details for an IP Pool GET all IP Pools that have Associated IPs Update an IP Pool Name Delete an IP Pool Add a Batch of IPs to an IP Pool Get IPs Assigned to an IP Pool Delete a Batch of IPs from an IP Pool Assign a Batch of Subusers to an IP Get a List of Subusers Assigned to an IP Delete a Batch of Subusers from an IP

IP Pools

IP Pools API Overview Create an IP pool Retrieve all IP pools Retrieve all the IPs in a specified pool Add an IP address to a pool Remove an IP address from a pool Rename an IP pool Delete an IP pool

IP Warmup

IP Address Warmup API Overview Start warming up an IP address Retrieve the warmup status for a specific IP address Retrieve all IPs currently in warmup Stop warming up an IP address

Link Branding

Link Branding API Overview Create a branded link Validate a branded link Retrieve the default branded link Retrieve a branded link Retrieve all branded links Retrieve a subuser's branded link Associate a branded link with a subuser Disassociate a branded link from a subuser Update a branded link Delete a branded link

Reverse DNS

Reverse DNS API Overview Set up reverse DNS Validate a reverse DNS record Retrieve a reverse DNS record Retrieve all reverse DNS records Delete a reverse DNS record

Sender Verification

Sender Verification API Overview Create Verified Sender Request Resend Verified Sender Request Verify Sender Request Get All Verified Senders Edit Verified Sender Delete Verified Sender Completed Steps Domain Warn List

SendGrid Engagement Quality API

SendGrid Engagement Quality API Overview Get Engagement Quality Scores Get Subusers' Engagement Quality Scores

Design Library

Design Library API Overview Create Design Duplicate Design Get Design List Designs Update Design Duplicate SendGrid Pre-built Design Get SendGrid Pre-built Design List SendGrid Pre-built Designs Delete Design

Email Activity

Email Activity API Overview Filter Messages by ID Filter All Messages Request a CSV Download CSV

Event Tracking

Tracking Settings

Event Tracking API Overview Retrieve Tracking Settings Retrieve Click Track Settings Update Click Tracking Settings Retrieve Google Analytics Settings Update Google Analytics Settings Get Open Tracking Settings Update Open Tracking Settings Retrieve Subscription Tracking Settings Update Subscription Tracking Settings

Stats

Statistics API Overview Retrieve global email statistics Retrieve email statistics by browser.Retrieve stats by a specific client type.Retrieve email statistics by client type.Retrieve email statistics by country and state/province.Retrieve email statistics by device type.Retrieve email statistics by mailbox provider.

Webhooks

Webhooks API Overview Create an Event Webhook Test Event Notification Settings Get an Event Webhook Get All Event Webhooks Toggle Signature Verification for an Event Webhook Get Signed Event Webhook's Public Key Update an Event Webhook Delete an Event Webhook Retrieve Parse Webhook settings Retrieves Inbound Parse Webhook statistics.

Inbound Parse

Inbound Parse API Overview Create a parse setting Retrieve a specific parse setting Retrieve all parse settings Update a parse setting Delete a parse setting

Legacy Marketing Campaigns

Campaigns API

Legacy Campaigns API Overview Create a Campaign Retrieve a single campaign Retrieve all Campaigns Update a Campaign Send a Campaign Send a Test Campaign Schedule a Campaign View Scheduled Time of a Campaign Update a Scheduled Campaign Unschedule a Scheduled Campaign Delete a Campaign

Categories

Legacy Categories API Overview Retrieve all categories Retrieve Email Statistics for Categories Retrieve sums of email stats for each category

Contacts API - Custom Fields

Legacy Custom Fields API Overview Create a Custom Field Retrieve a Custom Field Retrieve all custom fields Retrieve reserved fields Delete a Custom Field

Contacts API - Lists

Legacy Lists API Overview Create a List Retrieve a single list Retrieve all lists Add a Single Recipient to a List Add Multiple Recipients to a List Retrieve all recipients on a List Delete a Single Recipient from a Single List Update a List Delete a List Delete Multiple lists

Contacts API - Recipients

Legacy Recipients API Overview Add recipients Get Recipient Upload Status Retrieve a single recipient Retrieve recipients Search recipients Retrieve the lists that a recipient is on Retrieve a Count of Recipients Retrieve the count of billable recipients Update Recipient Delete a Recipient Delete Recipients

Contacts API - Segments

Legacy Segments API Overview Create a Segment Retrieve a segment Retrieve all segments Retrieve recipients on a segment Delete a segment

Sender Identities API

Legacy Sender Identities API Overview Create a Sender Identity Resend Sender Identity Verification View a Sender Identity Get all Sender Identities Update a Sender Identity Delete a Sender Identity

New Marketing Campaigns

Contacts

Contacts API Overview Add or Update a Contact Import Contacts Import Contacts Status Get a Contact by ID Get Batched Contacts by IDs Get Contacts by Emails Search Contacts Get Sample Contacts Get Total Contact Count Export Contacts Export Contacts Status Get All Existing Exports Delete Contacts Delete a Contact Identifier Get Contacts by Identifiers

Custom Fields

Custom Fields API Overview Create Custom Field Definition Get All Field Definitions Update Custom Field Definition Delete Custom Field Definition

Lists

Lists API Overview Create List Get a List by ID Get List Contact Count Get All Lists Update List Remove Contacts from a List Delete a list

Marketing Campaign Stats

Marketing Campaigns Statistics API Overview Get Automation Stats by ID Get Automation Click Tracking Stats by ID Get All Automation Stats Export Automation Stats Get Single Send Stats by ID Get Single Send Click Tracking Stats by ID Get All Single Sends Stats Export Single Send Stats

Segmenting Contacts

Segments API Overview Get Segment by ID Get List of Segments Delete Segment

Segmenting Contacts V2

Segments v2 API Overview Create Segment Get Segment by ID Get List of Segments Refresh Segment Update Segment Delete segment

Single Sends

Single Sends API Overview Create Single Send Duplicate Single Send Get Single Send by ID Get Single Sends Search Get All Single Sends Get All Categories Update Single Send Schedule Single Send Delete Single Send Schedule Delete Single Send by ID Bulk Delete Single Sends

Integrations

Create an Integration Get an Integration by ID Get All Integrations Update an Integration Bulk Delete Integrations

Senders

Senders API Overview Create a Sender Get a list of all Senders Get a specific Sender Update a Sender Delete a Sender Resend a Sender verification

Send Test E-Mail

Send a Test Marketing Email

Security

API Keys

API Keys API Overview Create API keys Retrieve an existing API Key Retrieve all API Keys belonging to the authenticated user Update API key name Update API key name and scopes Delete API keys

API Key permissions

API Key Permissions API Overview Retrieve a list of scopes for which this user has access.

Enforced TLS

Enforced TLS API Overview Retrieve current Enforced TLS settings.Update Enforced TLS settings

IP access management

IP Access Management API Overview Retrieve a specific allowed IP Retrieve a list of currently allowed IPs Retrieve all recent access attempts Add one or more IPs to the allow list Remove a specific IP from the allowed list Remove one or more IPs from the allow list

Settings

Alerts

Alerts API Overview Create a new Alert Retrieve a specific alert Retrieve all alerts Update an alert Delete an alert

Mail Settings

Mail Settings API Overview Retrieve all mail settings Retrieve address whitelist mail settings Update address whitelist mail settings Retrieve bounce purge mail settings Update bounce purge mail settings Retrieve forward bounce mail settings Update forward bounce mail settings Retrieve forward spam mail settings Update forward spam mail settings Retrieve footer mail settings Update footer mail settings Retrieve legacy template mail settings Update template mail settings

Partner Settings

Partner Settings API Overview Retrieve a list of all partner settings

Recipients' Data Erasure API

Recipients' Data Erasure API Overview Erase Recipients' Email Data

Subusers API

Subusers API Overview Create Subuser Retrieve Subuser Reputations List all Subusers Enable/Disable a Subuser Enable/Disable Website Access for a Subuser Update IPs assigned to a Subuser Delete a Subuser Get the Credits for a Subuser Update the Credits for a Subuser Update the remaining credits for a Subuser

Subuser Statistics

Subuser Statistics API Overview Retrieve email statistics for your subuser Retrieve the monthly email statistics for a single subuser Retrieve monthly stats for all subusers Retrieve the totals for each email statistic metric for all subusers.

Teammates

Teammates API Overview Invite teammate Resend teammate invite Retrieve specific teammate Retrieve all teammates Retrieve all pending teammates Retrieve access requests Approve access request Update teammate's permissions Deny access request Delete teammate Delete pending teammate Get Teammate Subuser Access

Users API

Users API Overview Get a user's account information.Retrieve your account email address Update your account email address Retrieve your credit balance Update your password Get a user's profile Update a user's profile Retrieve your username Update your username

Single Sign-On

Single Sign-On Certificates

SSO Certificates API Overview Create an SSO Certificate Get an SSO Certificate Get All SSO Certificates by Integration Update SSO Certificate Delete an SSO Certificate

Single Sign-On Settings

SSO Integrations API Overview Create an SSO Integration Get an SSO Integration Get All SSO Integrations Update an SSO Integration Delete an SSO Integration

Single Sign-On Teammates

SSO Teammates API Overview Create SSO Teammate Edit an SSO Teammate

Suppression Management

Blocks API

Blocks API Overview Retrieve a specific block Retrieve all blocks Delete a specific block Delete blocks

Bounces API

Bounces API Overview Retrieve a Bounce Retrieve bounces by specific classification Retrieve bounce totals by classification Retrieve all bounces Delete a bounce Delete bounces

Invalid E-Mails API

Invalid Emails API Overview Retrieve a specific invalid email Retrieve all invalid emails Delete a specific invalid email Delete invalid emails

Spam Reports API

Spam Reports API Overview Retrieve a specific spam report Retrieve all spam reports Delete a specific spam report Delete spam reports

Suppressions - Global Suppressions

Global Suppressions API Overview Add recipient addresses to the global suppression group.Retrieve a Global Suppression Retrieve all Global Suppressions Delete a Global Suppression

Suppressions - Suppressions

Suppressions API Overview Add suppressions to a suppression group Retrieve all suppression groups for an email address Retrieve all suppressions for a suppression group Search for suppressions within a group Retrieve all suppressions Delete a suppression from a suppression group

Suppressions - Unsubscribe Groups

Unsubscribe Groups API Overview Create a new suppression group Get information on a single suppression group.Retrieve all suppression groups associated with the user.Update a suppression group.Delete a Suppression Group

Templates

Transactional Templates

Templates API Overview Create a transactional template.Duplicate a transactional template.Retrieve a single transactional template.Retrieve paged transactional templates.Edit a transactional template.Delete a template.

Transactional Templates Versions

Templates Versions API Overview Create a new transactional template version.Activate a transactional template version.Retrieve a specific transactional template version.Edit a transactional template version.Delete a transactional template version.

Twilio SendGrid Docs

Log in
Sign up

Rate this page:

12345

On this page

API Overview
Libraries
How to use on-behalf-of

How to use on-behalf-of

On Behalf Of

API Overview

Welcome to SendGrid's Web API v3! This API is RESTful, fully featured, easy to integrate with, and offers support in 7 different languages.

Libraries

C#
Go
Java
Node.js
PHP
Python
Ruby

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. Use this header to automate bulk updates or to administer a Subuser or account without changing the authentication in your code.

(warning)

Warning

The on-behalf-of header does not work with the Mail Send API.

How to use on-behalf-of

On Behalf Of generates the API call as if the Subuser or customer account is making the call. When authenticating and using the on-behalf-of header, you must use the parent account's API key credentials.

On Behalf Of accepts either a Subuser username or customer account ID, depending on which type of sub-account structure you are administering. Subusers function like separate SendGrid sub-accounts, and they're available to all customers on Pro and Premier plans. Customer accounts also act as separate sub-accounts that are managed by a parent account; however, customer accounts are available only to companies that have a formal reseller partnership with Twilio SendGrid.

See Subusers for more information about working with Subusers. See the Account Provisioning API for more information about managing customer accounts.

When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID.

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.

on-behalf-of: <subuser-username>

On Behalf Of SubuserOn Behalf Of Customer Account


_10curl --request GET \
_10  --url 'https://api.sendgrid.com/v3/stats?start_date=2018-02-01&aggregated_by=day' \
_10  --header 'authorization: Bearer <SENDGRID_API_KEY>' \
_10  --header 'on-behalf-of: <subuser-username>'


_10curl --request GET \
_10  --url 'https://api.sendgrid.com/v3/stats?start_date=2018-02-01&aggregated_by=day' \
_10  --header 'authorization: Bearer <SENDGRID_API_KEY>' \
_10  --header 'on-behalf-of: account-id <account-id>'

Rate this page:

12345

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 by visiting Twilio's Stack Overflow Collective or browsing the SendGrid tag on Stack Overflow.

Terms of service

Copyright © 2024 Twilio Inc.