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 Classroom.

The following is a complete list of all possible permissions that you may assign to an API Key.

Table of Contents

Alerts

1
2
3
4
5
6
"scopes": [
  "alerts.create",
  "alerts.delete",
  "alerts.read",
  "alerts.update"
]

API Keys

1
2
3
4
5
6
"scopes": [
  "api_keys.create",
  "api_keys.delete",
  "api_keys.read",
  "api_keys.update"
]

ASM Groups

1
2
3
4
5
6
"scopes": [
  "asm.groups.create",
  "asm.groups.delete",
  "asm.groups.read",
  "asm.groups.update"
]

Billing

1
2
3
4
5
6
"scopes": [
  "billing.create",
  "billing.delete",
  "billing.read",
  "billing.update"
]

As explained in the Classroom, Billing permissions are mutually exclusive from all others. An API Key can either have Billing Permissions, or any other set of Permissions.

Categories

1
2
3
4
5
6
7
8
"scopes": [
  "categories.create",
  "categories.delete",
  "categories.read",
  "categories.update",
  "categories.stats.read",
  "categories.stats.sums.read"
]

Credentials

1
2
3
4
5
6
"scopes": [
  "credentials.create",
  "credentials.delete",
  "credentials.read",
  "credentials.update"
]

Stats

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"scopes": [
  "email_activity.read",
  "stats.read",
  "stats.global.read",
  "browsers.stats.read",
  "devices.stats.read",
  "geo.stats.read",
  "mailbox_providers.stats.read",
  "clients.desktop.stats.read",
  "clients.phone.stats.read",
  "clients.stats.read",
  "clients.tablet.stats.read",
  "clients.webmail.stats.read"
]

IPs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"scopes": [
  "ips.assigned.read",
  "ips.read",
  "ips.pools.create",
  "ips.pools.delete",
  "ips.pools.read",
  "ips.pools.update",
  "ips.pools.ips.create",
  "ips.pools.ips.delete",
  "ips.pools.ips.read",
  "ips.pools.ips.update",
  "ips.warmup.create",
  "ips.warmup.delete",
  "ips.warmup.read",
  "ips.warmup.update"
]

Mail Settings

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
"scopes": [
  "mail_settings.address_whitelist.read",
  "mail_settings.address_whitelist.update",
  "mail_settings.bcc.read",
  "mail_settings.bcc.update",
  "mail_settings.bounce_purge.read",
  "mail_settings.bounce_purge.update",
  "mail_settings.footer.read",
  "mail_settings.footer.update",
  "mail_settings.forward_bounce.read",
  "mail_settings.forward_bounce.update",
  "mail_settings.forward_spam.read",
  "mail_settings.forward_spam.update",
  "mail_settings.plain_content.read",
  "mail_settings.plain_content.update",
  "mail_settings.read",
  "mail_settings.spam_check.read",
  "mail_settings.spam_check.update",
  "mail_settings.template.read",
  "mail_settings.template.update"
]

Mail

1
2
3
4
5
6
7
"scopes": [
  "mail.batch.create",
  "mail.batch.delete",
  "mail.batch.read",
  "mail.batch.update",
  "mail.send"
]

Marketing Campaigns

1
2
3
4
5
6
"scopes": [
  "marketing_campaigns.create",
  "marketing_campaigns.delete",
  "marketing_campaigns.read",
  "marketing_campaigns.update"
]

Partner Settings

1
2
3
4
5
6
7
"scopes": [
  "partner_settings.new_relic.read",
  "partner_settings.new_relic.update",
  "partner_settings.read",
  "partner_settings.sendwithus.read",
  "partner_settings.sendwithus.update"
]

Scheduled Sends

1
2
3
4
5
6
"scopes": [
  "user.scheduled_sends.create",
  "user.scheduled_sends.delete",
  "user.scheduled_sends.read",
  "user.scheduled_sends.update"
]

Subusers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
"scopes": [
  "subusers.create",
  "subusers.delete",
  "subusers.read",
  "subusers.update",
  "subusers.credits.create",
  "subusers.credits.delete",
  "subusers.credits.read",
  "subusers.credits.update",
  "subusers.credits.remaining.create",
  "subusers.credits.remaining.delete",
  "subusers.credits.remaining.read",
  "subusers.credits.remaining.update",
  "subusers.monitor.create",
  "subusers.monitor.delete",
  "subusers.monitor.read",
  "subusers.monitor.update",
  "subusers.reputations.read",
  "subusers.stats.read",
  "subusers.stats.monthly.read",
  "subusers.stats.sums.read"
  "subusers.summary.read"
]

Suppressions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
"scopes": [
  "suppression.create",
  "suppression.delete",
  "suppression.read",
  "suppression.update",
  "suppression.bounces.create",
  "suppression.bounces.read",
  "suppression.bounces.update",
  "suppression.bounces.delete",
  "suppression.blocks.create",
  "suppression.blocks.read",
  "suppression.blocks.update",
  "suppression.blocks.delete",
  "suppression.invalid_emails.create",
  "suppression.invalid_emails.read",
  "suppression.invalid_emails.update",
  "suppression.invalid_emails.delete",
  "suppression.spam_reports.create",
  "suppression.spam_reports.read",
  "suppression.spam_reports.update",
  "suppression.spam_reports.delete",
  "suppression.unsubscribes.create",
  "suppression.unsubscribes.read",
  "suppression.unsubscribes.update",
  "suppression.unsubscribes.delete"
]

Teammates

1
2
3
4
5
6
"scopes": [
  "teammates.create",
  "teammates.read",
  "teammates.update",
  "teammates.delete"
]

Templates

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"scopes": [
  "templates.create",
  "templates.delete",
  "templates.read",
  "templates.update",
  "templates.versions.activate.create",
  "templates.versions.activate.delete",
  "templates.versions.activate.read",
  "templates.versions.activate.update",
  "templates.versions.create",
  "templates.versions.delete",
  "templates.versions.read",
  "templates.versions.update"
]

Tracking

1
2
3
4
5
6
7
8
9
10
11
"scopes": [
  "tracking_settings.click.read",
  "tracking_settings.click.update",
  "tracking_settings.google_analytics.read",
  "tracking_settings.google_analytics.update",
  "tracking_settings.open.read",
  "tracking_settings.open.update",
  "tracking_settings.read",
  "tracking_settings.subscription.read",
  "tracking_settings.subscription.update"
]

User Settings

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
"scopes": [
  "user.account.read",
  "user.credits.read",
  "user.email.create",
  "user.email.delete",
  "user.email.read",
  "user.email.update",
  "user.multifactor_authentication.create",
  "user.multifactor_authentication.delete",
  "user.multifactor_authentication.read",
  "user.multifactor_authentication.update",
  "user.password.read",
  "user.password.update",
  "user.profile.read",
  "user.profile.update",
  "user.settings.enforced_tls.read",
  "user.settings.enforced_tls.update",
  "user.timezone.read",
  "user.timezone.update",
  "user.username.read",
  "user.username.update"
]

Webhook

1
2
3
4
5
6
7
8
9
10
11
12
"scopes": [
  "user.webhooks.event.settings.read",
  "user.webhooks.event.settings.update",
  "user.webhooks.event.test.create",
  "user.webhooks.event.test.read",
  "user.webhooks.event.test.update",
  "user.webhooks.parse.settings.create",
  "user.webhooks.parse.settings.delete",
  "user.webhooks.parse.settings.read",
  "user.webhooks.parse.settings.update",
  "user.webhooks.parse.stats.read"
]

Whitelabel

1
2
3
4
5
6
"scopes": [
  "whitelabel.create",
  "whitelabel.delete",
  "whitelabel.read",
  "whitelabel.update"
]

Whitelist

1
2
3
4
5
6
7
"scopes": [
  "access_settings.activity.read",
  "access_settings.whitelist.create",
  "access_settings.whitelist.delete",
  "access_settings.whitelist.read",
  "access_settings.whitelist.update"
]

Admin API Key Scopes

Below is a complete list of every API Key scope to be given to an admin level API Key.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
"scopes": [
  "access_settings.activity.read",
  "access_settings.whitelist.create",
  "access_settings.whitelist.delete",
  "access_settings.whitelist.read",
  "access_settings.whitelist.update",
  "alerts.create",
  "alerts.delete",
  "alerts.read",
  "alerts.update",
  "api_keys.create",
  "api_keys.delete",
  "api_keys.read",
  "api_keys.update",
  "asm.groups.create",
  "asm.groups.delete",
  "asm.groups.read",
  "asm.groups.update",
  "billing.create",
  "billing.delete",
  "billing.read",
  "billing.update",
  "browsers.stats.read",
  "categories.create",
  "categories.delete",
  "categories.read",
  "categories.stats.read",
  "categories.stats.sums.read",
  "categories.update",
  "clients.desktop.stats.read",
  "clients.phone.stats.read",
  "clients.stats.read",
  "clients.tablet.stats.read",
  "clients.webmail.stats.read",
  "devices.stats.read",
  "email_activity.read",
  "geo.stats.read",
  "ips.assigned.read",
  "ips.pools.create",
  "ips.pools.delete",
  "ips.pools.ips.create",
  "ips.pools.ips.delete",
  "ips.pools.ips.read",
  "ips.pools.ips.update",
  "ips.pools.read",
  "ips.pools.update",
  "ips.read",
  "ips.warmup.create",
  "ips.warmup.delete",
  "ips.warmup.read",
  "ips.warmup.update",
  "mail_settings.address_whitelist.read",
  "mail_settings.address_whitelist.update",
  "mail_settings.bcc.read",
  "mail_settings.bcc.update",
  "mail_settings.bounce_purge.read",
  "mail_settings.bounce_purge.update",
  "mail_settings.footer.read",
  "mail_settings.footer.update",
  "mail_settings.forward_bounce.read",
  "mail_settings.forward_bounce.update",
  "mail_settings.forward_spam.read",
  "mail_settings.forward_spam.update",
  "mail_settings.plain_content.read",
  "mail_settings.plain_content.update",
  "mail_settings.read",
  "mail_settings.spam_check.read",
  "mail_settings.spam_check.update",
  "mail_settings.template.read",
  "mail_settings.template.update",
  "mail.batch.create",
  "mail.batch.delete",
  "mail.batch.read",
  "mail.batch.update",
  "mail.send",
  "mailbox_providers.stats.read",
  "marketing_campaigns.create",
  "marketing_campaigns.delete",
  "marketing_campaigns.read",
  "marketing_campaigns.update",
  "partner_settings.new_relic.read",
  "partner_settings.new_relic.update",
  "partner_settings.read",
  "partner_settings.sendwithus.read",
  "partner_settings.sendwithus.update",
  "stats.global.read",
  "stats.read",
  "subusers.create",
  "subusers.credits.create",
  "subusers.credits.delete",
  "subusers.credits.read",
  "subusers.credits.remaining.create",
  "subusers.credits.remaining.delete",
  "subusers.credits.remaining.read",
  "subusers.credits.remaining.update",
  "subusers.credits.update",
  "subusers.delete",
  "subusers.monitor.create",
  "subusers.monitor.delete",
  "subusers.monitor.read",
  "subusers.monitor.update",
  "subusers.read",
  "subusers.reputations.read",
  "subusers.stats.monthly.read",
  "subusers.stats.read",
  "subusers.stats.sums.read",
  "subusers.summary.read",
  "subusers.update",
  "suppression.blocks.create",
  "suppression.blocks.delete",
  "suppression.blocks.read",
  "suppression.blocks.update",
  "suppression.bounces.create",
  "suppression.bounces.delete",
  "suppression.bounces.read",
  "suppression.bounces.update",
  "suppression.create",
  "suppression.delete",
  "suppression.invalid_emails.create",
  "suppression.invalid_emails.delete",
  "suppression.invalid_emails.read",
  "suppression.invalid_emails.update",
  "suppression.read",
  "suppression.spam_reports.create",
  "suppression.spam_reports.delete",
  "suppression.spam_reports.read",
  "suppression.spam_reports.update",
  "suppression.unsubscribes.create",
  "suppression.unsubscribes.delete",
  "suppression.unsubscribes.read",
  "suppression.unsubscribes.update",
  "suppression.update",
  "teammates.create",
  "teammates.read",
  "teammates.update",
  "teammates.delete",
  "templates.create",
  "templates.delete",
  "templates.read",
  "templates.update",
  "templates.versions.activate.create",
  "templates.versions.activate.delete",
  "templates.versions.activate.read",
  "templates.versions.activate.update",
  "templates.versions.create",
  "templates.versions.delete",
  "templates.versions.read",
  "templates.versions.update",
  "tracking_settings.click.read",
  "tracking_settings.click.update",
  "tracking_settings.google_analytics.read",
  "tracking_settings.google_analytics.update",
  "tracking_settings.open.read",
  "tracking_settings.open.update",
  "tracking_settings.read",
  "tracking_settings.subscription.read",
  "tracking_settings.subscription.update",
  "user.account.read",
  "user.credits.read",
  "user.email.create",
  "user.email.delete",
  "user.email.read",
  "user.email.update",
  "user.multifactor_authentication.create",
  "user.multifactor_authentication.delete",
  "user.multifactor_authentication.read",
  "user.multifactor_authentication.update",
  "user.password.read",
  "user.password.update",
  "user.profile.read",
  "user.profile.update",
  "user.scheduled_sends.create",
  "user.scheduled_sends.delete",
  "user.scheduled_sends.read",
  "user.scheduled_sends.update",
  "user.settings.enforced_tls.read",
  "user.settings.enforced_tls.update",
  "user.timezone.read",
  "user.username.read",
  "user.username.update",
  "user.webhooks.event.settings.read",
  "user.webhooks.event.settings.update",
  "user.webhooks.event.test.create",
  "user.webhooks.event.test.read",
  "user.webhooks.event.test.update",
  "user.webhooks.parse.settings.create",
  "user.webhooks.parse.settings.delete",
  "user.webhooks.parse.settings.read",
  "user.webhooks.parse.settings.update",
  "user.webhooks.parse.stats.read",
  "whitelabel.create",
  "whitelabel.delete",
  "whitelabel.read",
  "whitelabel.update"
]