Welcome to SendGrid's Web API v3! This API is RESTful and offers support in seven different languages.
API Keys can be used to authenticate the use of SendGrid's v3 Web API, or the Mail API endpoint. API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissions, please visit our API Keys docs.
The following is a complete list of all possible permissions that you may assign to an API Key.
When updating a key to include user or subuser scopes, use basic authentication.
1"scopes": [2"alerts.create",3"alerts.delete",4"alerts.read",5"alerts.update"6]
1"scopes": [2"api_keys.create",3"api_keys.delete",4"api_keys.read",5"api_keys.update"6]
1"scopes": [2"asm.groups.create",3"asm.groups.delete",4"asm.groups.read",5"asm.groups.update"6]
1"scopes": [2"billing.create",3"billing.delete",4"billing.read",5"billing.update"6]
Billing permissions are mutually exclusive from all other permissions. An API Key can have either Billing Permissions or any other set of Permissions but not both.
1"scopes": [2"categories.create",3"categories.delete",4"categories.read",5"categories.update",6"categories.stats.read",7"categories.stats.sums.read"8]
1"scopes": [2"email_activity.read",3"stats.read",4"stats.global.read",5"browsers.stats.read",6"devices.stats.read",7"geo.stats.read",8"mailbox_providers.stats.read",9"clients.desktop.stats.read",10"clients.phone.stats.read",11"clients.stats.read",12"clients.tablet.stats.read",13"clients.webmail.stats.read"14]
1"scopes": [2"ips.assigned.read",3"ips.read",4"ips.pools.create",5"ips.pools.delete",6"ips.pools.read",7"ips.pools.update",8"ips.pools.ips.create",9"ips.pools.ips.delete",10"ips.pools.ips.read",11"ips.pools.ips.update",12"ips.warmup.create",13"ips.warmup.delete",14"ips.warmup.read",15"ips.warmup.update"16]
1"scopes": [2"mail_settings.address_whitelist.read",3"mail_settings.address_whitelist.update",4"mail_settings.bounce_purge.read",5"mail_settings.bounce_purge.update",6"mail_settings.footer.read",7"mail_settings.footer.update",8"mail_settings.forward_bounce.read",9"mail_settings.forward_bounce.update",10"mail_settings.forward_spam.read",11"mail_settings.forward_spam.update",12"mail_settings.template.read",13"mail_settings.template.update"14]
1"scopes": [2"mail.batch.create",3"mail.batch.delete",4"mail.batch.read",5"mail.batch.update",6"mail.send"7]
1"scopes": [2"marketing_campaigns.create",3"marketing_campaigns.delete",4"marketing_campaigns.read",5"marketing_campaigns.update"6]
1"scopes": [2"partner_settings.new_relic.read",3"partner_settings.new_relic.update",4"partner_settings.read"5]
1"scopes": [2"user.scheduled_sends.create",3"user.scheduled_sends.delete",4"user.scheduled_sends.read",5"user.scheduled_sends.update"6]
1"scopes": [2"subusers.create",3"subusers.delete",4"subusers.read",5"subusers.update",6"subusers.credits.create",7"subusers.credits.delete",8"subusers.credits.read",9"subusers.credits.update",10"subusers.credits.remaining.create",11"subusers.credits.remaining.delete",12"subusers.credits.remaining.read",13"subusers.credits.remaining.update",14"subusers.monitor.create",15"subusers.monitor.delete",16"subusers.monitor.read",17"subusers.monitor.update",18"subusers.reputations.read",19"subusers.stats.read",20"subusers.stats.monthly.read",21"subusers.stats.sums.read"22"subusers.summary.read"23]
1"scopes": [2"suppression.create",3"suppression.delete",4"suppression.read",5"suppression.update",6"suppression.bounces.create",7"suppression.bounces.read",8"suppression.bounces.update",9"suppression.bounces.delete",10"suppression.blocks.create",11"suppression.blocks.read",12"suppression.blocks.update",13"suppression.blocks.delete",14"suppression.invalid_emails.create",15"suppression.invalid_emails.read",16"suppression.invalid_emails.update",17"suppression.invalid_emails.delete",18"suppression.spam_reports.create",19"suppression.spam_reports.read",20"suppression.spam_reports.update",21"suppression.spam_reports.delete",22"suppression.unsubscribes.create",23"suppression.unsubscribes.read",24"suppression.unsubscribes.update",25"suppression.unsubscribes.delete"26]
1"scopes": [2"teammates.create",3"teammates.read",4"teammates.update",5"teammates.delete"6]
1"scopes": [2"templates.create",3"templates.delete",4"templates.read",5"templates.update",6"templates.versions.activate.create",7"templates.versions.activate.delete",8"templates.versions.activate.read",9"templates.versions.activate.update",10"templates.versions.create",11"templates.versions.delete",12"templates.versions.read",13"templates.versions.update"14]
1"scopes": [2"tracking_settings.click.read",3"tracking_settings.click.update",4"tracking_settings.google_analytics.read",5"tracking_settings.google_analytics.update",6"tracking_settings.open.read",7"tracking_settings.open.update",8"tracking_settings.read",9"tracking_settings.subscription.read",10"tracking_settings.subscription.update"11]
1"scopes": [2"user.account.read",3"user.credits.read",4"user.email.create",5"user.email.delete",6"user.email.read",7"user.email.update",8"user.multifactor_authentication.create",9"user.multifactor_authentication.delete",10"user.multifactor_authentication.read",11"user.multifactor_authentication.update",12"user.password.read",13"user.password.update",14"user.profile.read",15"user.profile.update",16"user.settings.enforced_tls.read",17"user.settings.enforced_tls.update",18"user.timezone.read",19"user.timezone.update",20"user.username.read",21"user.username.update"22]
1"scopes": [2"user.webhooks.event.settings.read",3"user.webhooks.event.settings.update",4"user.webhooks.event.test.create",5"user.webhooks.event.test.read",6"user.webhooks.event.test.update",7"user.webhooks.parse.settings.create",8"user.webhooks.parse.settings.delete",9"user.webhooks.parse.settings.read",10"user.webhooks.parse.settings.update",11"user.webhooks.parse.stats.read"12]
1"scopes": [2"whitelabel.create",3"whitelabel.delete",4"whitelabel.read",5"whitelabel.update"6]
1"scopes": [2"access_settings.activity.read",3"access_settings.whitelist.create",4"access_settings.whitelist.delete",5"access_settings.whitelist.read",6"access_settings.whitelist.update"7]
Below is a complete list of every API Key scope to be given to an admin level API Key.
1"scopes": [2"access_settings.activity.read",3"access_settings.whitelist.create",4"access_settings.whitelist.delete",5"access_settings.whitelist.read",6"access_settings.whitelist.update",7"alerts.create",8"alerts.delete",9"alerts.read",10"alerts.update",11"api_keys.create",12"api_keys.delete",13"api_keys.read",14"api_keys.update",15"asm.groups.create",16"asm.groups.delete",17"asm.groups.read",18"asm.groups.update",19"billing.create",20"billing.delete",21"billing.read",22"billing.update",23"browsers.stats.read",24"categories.create",25"categories.delete",26"categories.read",27"categories.stats.read",28"categories.stats.sums.read",29"categories.update",30"clients.desktop.stats.read",31"clients.phone.stats.read",32"clients.stats.read",33"clients.tablet.stats.read",34"clients.webmail.stats.read",35"devices.stats.read",36"email_activity.read",37"geo.stats.read",38"ips.assigned.read",39"ips.pools.create",40"ips.pools.delete",41"ips.pools.ips.create",42"ips.pools.ips.delete",43"ips.pools.ips.read",44"ips.pools.ips.update",45"ips.pools.read",46"ips.pools.update",47"ips.read",48"ips.warmup.create",49"ips.warmup.delete",50"ips.warmup.read",51"ips.warmup.update",52"mail_settings.address_whitelist.read",53"mail_settings.address_whitelist.update",54"mail_settings.bounce_purge.read",55"mail_settings.bounce_purge.update",56"mail_settings.footer.read",57"mail_settings.footer.update",58"mail_settings.forward_bounce.read",59"mail_settings.forward_bounce.update",60"mail_settings.forward_spam.read",61"mail_settings.forward_spam.update",62"mail_settings.plain_content.read",63"mail_settings.plain_content.update",64"mail_settings.read",,65"mail_settings.template.read",66"mail_settings.template.update",67"mail.batch.create",68"mail.batch.delete",69"mail.batch.read",70"mail.batch.update",71"mail.send",72"mailbox_providers.stats.read",73"marketing_campaigns.create",74"marketing_campaigns.delete",75"marketing_campaigns.read",76"marketing_campaigns.update",77"partner_settings.new_relic.read",78"partner_settings.new_relic.update",79"partner_settings.read",80"stats.global.read",81"stats.read",82"subusers.create",83"subusers.credits.create",84"subusers.credits.delete",85"subusers.credits.read",86"subusers.credits.remaining.create",87"subusers.credits.remaining.delete",88"subusers.credits.remaining.read",89"subusers.credits.remaining.update",90"subusers.credits.update",91"subusers.delete",92"subusers.monitor.create",93"subusers.monitor.delete",94"subusers.monitor.read",95"subusers.monitor.update",96"subusers.read",97"subusers.reputations.read",98"subusers.stats.monthly.read",99"subusers.stats.read",100"subusers.stats.sums.read",101"subusers.summary.read",102"subusers.update",103"suppression.blocks.create",104"suppression.blocks.delete",105"suppression.blocks.read",106"suppression.blocks.update",107"suppression.bounces.create",108"suppression.bounces.delete",109"suppression.bounces.read",110"suppression.bounces.update",111"suppression.create",112"suppression.delete",113"suppression.invalid_emails.create",114"suppression.invalid_emails.delete",115"suppression.invalid_emails.read",116"suppression.invalid_emails.update",117"suppression.read",118"suppression.spam_reports.create",119"suppression.spam_reports.delete",120"suppression.spam_reports.read",121"suppression.spam_reports.update",122"suppression.unsubscribes.create",123"suppression.unsubscribes.delete",124"suppression.unsubscribes.read",125"suppression.unsubscribes.update",126"suppression.update",127"teammates.create",128"teammates.read",129"teammates.update",130"teammates.delete",131"templates.create",132"templates.delete",133"templates.read",134"templates.update",135"templates.versions.activate.create",136"templates.versions.activate.delete",137"templates.versions.activate.read",138"templates.versions.activate.update",139"templates.versions.create",140"templates.versions.delete",141"templates.versions.read",142"templates.versions.update",143"tracking_settings.click.read",144"tracking_settings.click.update",145"tracking_settings.google_analytics.read",146"tracking_settings.google_analytics.update",147"tracking_settings.open.read",148"tracking_settings.open.update",149"tracking_settings.read",150"tracking_settings.subscription.read",151"tracking_settings.subscription.update",152"user.account.read",153"user.credits.read",154"user.email.create",155"user.email.delete",156"user.email.read",157"user.email.update",158"user.multifactor_authentication.create",159"user.multifactor_authentication.delete",160"user.multifactor_authentication.read",161"user.multifactor_authentication.update",162"user.password.read",163"user.password.update",164"user.profile.read",165"user.profile.update",166"user.scheduled_sends.create",167"user.scheduled_sends.delete",168"user.scheduled_sends.read",169"user.scheduled_sends.update",170"user.settings.enforced_tls.read",171"user.settings.enforced_tls.update",172"user.timezone.read",173"user.username.read",174"user.username.update",175"user.webhooks.event.settings.read",176"user.webhooks.event.settings.update",177"user.webhooks.event.test.create",178"user.webhooks.event.test.read",179"user.webhooks.event.test.update",180"user.webhooks.parse.settings.create",181"user.webhooks.parse.settings.delete",182"user.webhooks.parse.settings.read",183"user.webhooks.parse.settings.update",184"user.webhooks.parse.stats.read",185"whitelabel.create",186"whitelabel.delete",187"whitelabel.read",188"whitelabel.update"189]