Add Basic Event Support

[jameskbride]

This PR adds the ability to send delivered events to a user-defined webhook.

Context

Sendgrid has the ability to send events to a user-specified webhook. These events can be used to indicate if a message has been delivered, processed, dropped, bounced, etc. It would be useful during development to have the delivered events sent to a webhook to be able to test the webhook integration.

Changes

• Introduced a new environment variable, EVENT_DELIVERY_URL. When this environment variable is set sendgrid-mock will send delivered events to the specified URL when addMail() is called.
• Added axios as a dependency, which is used to send the event to a webhook.
• Implemented the delivered event.

Testing

Use the following Python script to start a mini test server:

import http.server
import socketserver

class MyHandler(http.server.SimpleHTTPRequestHandler):
    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        post_data = self.rfile.read(content_length)
        print(f'post_data: {post_data}')

        self.send_response(200)
        self.send_header('Content-type', 'text/plain')
        self.end_headers()

        response = b'POST request received:\n' + post_data
        self.wfile.write(response)

PORT = 8080

with socketserver.TCPServer(("", PORT), MyHandler) as httpd:
    print(f"Serving at port {PORT}")
    httpd.serve_forever()

1. Start the application with the EVENT_DELIVERY_URL set:

   API_KEY=sendgrid-api-key EVENT_DELIVERY_URL=http://localhost:8080 npm run dev

2. Send a request to v3/mail/send:

   curl --request POST \
     --url http://localhost:3000/v3/mail/send \
     --header 'Authorization: Bearer sendgrid-api-key' \
     --header 'Content-Type: application/json' \
     --header 'User-Agent: insomnia/9.3.2' \
     --data '{
     "personalizations": [
       {
         "to": [{
           "email": "to@example.com"
         }, {
           "email": "to2@example.com"
         }]
       }
     ],
     "from": {
       "email": "from@example.com"
     },
       "subject": "Some subject",
       "content": [
       {
         "type": "text/plain",
         "value": "important content"
       }
     ],
     "template_id": "test-template-id"
   }
   '

3. Validate that the request is received by sendgrid-mock and that the message is visible at http://localhost:1234
4. Validate in the test webhook server logs that an array of events (one for each recipient) has been delivered:

   Serving at port 8080
   post_data: b'[{"email":"to@example.com","timestamp":1721774043221,"event":"delivered","sg_event_id":"956446ce-f966-4456-8971-7db19f79628e","sg_message_id":"ee1bd797-8a0c-4e6a-9ad8-21034bbf853c","smtp-id":"68c8bb93-880a-4d6c-85fe-a9340b6eec50"},{"email":"to2@example.com","timestamp":1721774043221,"event":"delivered","sg_event_id":"9f8bb14d-ca80-4d75-89ac-b700c154c516","sg_message_id":"ee1bd797-8a0c-4e6a-9ad8-21034bbf853c","smtp-id":"2e443d89-c79c-4318-8496-2a630be26e81"}]'
   127.0.0.1 - - [23/Jul/2024 18:34:03] "POST / HTTP/1.1" 200 -

5. Restart the application without the EVENT_DELIVERY_URL set.
6. Send another request to v3/mail/send.
7. Validate that sendgrid-mock received the messages and that they're available in http://localhost:1234 .
8. Validate that the webhook server did not receive events this time.

Out of Scope

• This PR does not add support for unique arguments being added to the events, or custom arguments, but these could be supported in later PRs.
• Events other than delivered. We would need to have some condition (or randomness?) to know when to return other Sendgrid-supported events.

[jameskbride]

Hi @janjaali! Thanks for creating sendGrid-mock 😄 Let me know what you think of this PR; it would be great to be able to test event webhook integration with basic support for delivered events.

[janjaali]

Hi @jameskbride, thanks for your contribution. I didn't have this weekend a chance to look into your PR. Trying to have a look this week.

[jameskbride]

Looks great! Would you be so kind and add some words about this new feature in https://github.com/jameskbride/sendgrid-mock/blob/be2894273b91b069600f209c2d724e57dc0be5da/README.md#L30?

Done, thanks @janjaali!

[janjaali]

Released with https://github.com/janjaali/sendGrid-mock/releases/tag/v1.10.0. Thanks again for your contribution!

[jameskbride]

Awesome, appreciate the quick release!