You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Events are generated when email is processed by SendGrid and email service providers. There are two types of events - delivery and engagement events. Delivery events indicate the status of email delivery to the recipient. Engagement events indicate how the recipient is interacting with the email.
52
52
53
53
Here is a flow of email events:
@@ -181,7 +181,6 @@ Here is an event response that includes an example of each type of event:
181
181
```
182
182
183
183
### Delivery events
184
-
185
184
186
185
Delivery events include processed, dropped, delivered, deferred, and bounce.
187
186
@@ -195,7 +194,10 @@ Delivery events include processed, dropped, delivered, deferred, and bounce.
195
194
<tr>
196
195
<td><a name="processed"></a>Processed</td>
197
196
<td>Message has been received and is ready to be delivered.</td>
198
-
<td>```json
197
+
<td>
198
+
<divclass="gatsby-highlight"data-language="json">
199
+
<preclass="language-json" >
200
+
<codeclass="language-json">
199
201
[
200
202
{
201
203
"email":"example@test.com",
@@ -208,10 +210,13 @@ Delivery events include processed, dropped, delivered, deferred, and bounce.
@@ -292,7 +297,7 @@ Delivery events include processed, dropped, delivered, deferred, and bounce.
292
297
</table>
293
298
294
299
### Engagement events
295
-
300
+
296
301
Engagement events include open, click, spam report, unsubscribe, group unsubscribe, and group resubscribe.
297
302
298
303
<table class="table">
@@ -421,7 +426,7 @@ Engagement events include open, click, spam report, unsubscribe, group unsubscri
421
426
</table>
422
427
423
428
## Event objects
424
-
429
+
425
430
<table class="table">
426
431
<tr>
427
432
<th></th>
@@ -720,7 +725,7 @@ Engagement events include open, click, spam report, unsubscribe, group unsubscri
720
725
</table>
721
726
722
727
### JSON objects
723
-
728
+
724
729
- <a name="email"></a>`email` - the email address of the recipient
725
730
- <a name="timestamp"></a>`timestamp` - the <a href="https://en.wikipedia.org/wiki/Unix_time">UNIX timestamp</a> of when the message was sent
726
731
- <a name="event"></a>`event` - the event type. Possible values are processed, dropped, delivered, deferred, bounce, open, click, spam report, unsubscribe, group unsubscribe, and group resubscribe.
@@ -781,7 +786,7 @@ Array:
781
786
- <aname="asmgroupid"></a>`asm_group_id` - The ID of the unsubscribe group the recipient's email address is included in. ASM IDs correspond to the ID that is returned when you create an unsubscribe group.
782
787
- <aname="uniqueargs"></a>`unique_args` or `custom_args`
783
788
## Unique Arguments and Custom Arguments
784
-
789
+
785
790
Events generated by SendGrid can include [unique arguments]({{root_url}}/for-developers/sending-email/unique-arguments.html) or custom arguments.
786
791
787
792
<call-out>
@@ -791,7 +796,7 @@ Unique arguments and custom arguments essentially have the same function. Howeve
791
796
</call-out>
792
797
793
798
### Unique Arguments
794
-
799
+
795
800
To define and receive unique arguments when sending email with the [SMTP API]({{root_url}}/API_Reference/SMTP_API/index.html) or the [v2 Mail Send endpoint]({{root_url}}/API_Reference/Web_API/mail.html), use the `unique_args` parameter in the X-SMTPAPI header. For example, if you have an application and want to receive custom parameters such as the `userid` and the email `template`, you would submit them with the X-SMTPAPI header, as described [here]({{root_url}}/for-developers/sending-email/unique-arguments.html).
796
801
797
802
For example, if you include the following unique arguments in your x-smtpapi header for an email sent via the v2 Mail Send endpoint:
@@ -828,7 +833,7 @@ You can create unique arguments with the same words as reserved keys, such as "e
828
833
</call-out>
829
834
830
835
### Reserved Keys in Unique Arguments
831
-
836
+
832
837
```json
833
838
//for this example, assume we're sending to john.doe@sendgrid.com
834
839
{
@@ -843,7 +848,7 @@ You can create unique arguments with the same words as reserved keys, such as "e
843
848
```
844
849
845
850
### The resulting webhook call
846
-
851
+
847
852
```json
848
853
[
849
854
{
@@ -864,7 +869,7 @@ You'll notice that the unique arguments, "event" and "email", were overwritten b
864
869
</call-out>
865
870
866
871
### Custom Arguments
867
-
872
+
868
873
Any custom arguments that you include with an email sent through [v3 Mail Send]({{root_url}}/API_Reference/Web_API_v3/Mail/index.html) gets added to your Event Webhook response.
869
874
870
875
For example, if you were to include the following custom arguments in a personalization in your payload to the v3 Mail Send endpoint:
@@ -912,7 +917,7 @@ The Event Webhook response:
912
917
For emails sent through our Marketing Campaigns feature, we add Marketing Campaigns specific parameters to the Event Webhook. Both `marketing_campaign_name` and `marketing_campaign_id` are displayed as unique arguments in the event data.
913
918
914
919
### Example event from a standard (non-A/B test) campaign send:
915
-
920
+
916
921
```json
917
922
{
918
923
"category": [],
@@ -930,7 +935,7 @@ For emails sent through our Marketing Campaigns feature, we add Marketing Campai
930
935
```
931
936
932
937
### Example event from an A/B Test:
933
-
938
+
934
939
`marketing_campaign_version` is displayed in the event data for emails sent as part of an A/B Test. The value for `marketing_campaign_version` are returned as `A`, `B`, `C`, etc.
935
940
936
941
```json
@@ -952,7 +957,7 @@ For emails sent through our Marketing Campaigns feature, we add Marketing Campai
952
957
```
953
958
954
959
### Example event from the winning phase of an A/B Test:
955
-
960
+
956
961
```json
957
962
{
958
963
"category": [],
@@ -971,7 +976,7 @@ For emails sent through our Marketing Campaigns feature, we add Marketing Campai
971
976
```
972
977
973
978
### Legacy Marketing Email Unsubscribes
974
-
979
+
975
980
For emails sent through our Legacy Marketing Email tool, unsubscribes look like the following example:
976
981
977
982
```json
@@ -1013,7 +1018,7 @@ For emails sent through our Legacy Marketing Email tool, unsubscribes look like
1013
1018
```
1014
1019
1015
1020
## Additional Resources
1016
-
1021
+
1017
1022
-[Getting started with the Event Webhook]({{root_url}}/for-developers/tracking-events/getting-started-event-webhook.html)
1018
1023
-[Troubleshooting the event webhook]({{root_url}}/for-developers/tracking-events/troubleshooting.html)
1019
1024
-[An Event Webhook case study](https://sendgrid.com/blog/leveraging-sendgrids-event-api/)
0 commit comments