Skip to contentSkip to navigationSkip to topbar
Page toolsOn this page
Looking for more inspiration?Visit the

Authorization



API Overview

api-overview page anchor

The Twilio SendGrid Web REST API v3 provides SDK support in seven different languages.

C#(link takes you to an external page)Go(link takes you to an external page)Java(link takes you to an external page)Node.js(link takes you to an external page)PHP(link takes you to an external page)Python(link takes you to an external page)Ruby(link takes you to an external page)

API Key Permissions List

api-key-permissions-list page anchor

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.

(information)

Info

When updating a key to include user or subuser scopes, use basic authentication.

Alerts

alerts page anchor
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
]

Domain Authentication (formerly Whitelabel)

domain-authentication-formerly-whitelabel page anchor
1
"scopes": [
2
"whitelabel.create",
3
"whitelabel.delete",
4
"whitelabel.read",
5
"whitelabel.update"
6
]

Reverse DNS (formerly Whitelist)

reverse-dns-formerly-whitelist page anchor
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
]