janjaali / sendgrid-mock

SendGrid-Mock serves as a simple server mocking the sendgrid-apis for development purposes.

SendGrid-Mock

SendGrid-Mock serves as a simple server mocking the sendgrid-apis for development purposes.

Functionalities

HTTP API

• Send mails POST /v3/mail/send

• Retrieve sent mails GET /api/mails

  • Filter capabilities are included and can be combined:
    • To: GET /api/[email protected]
    • Subject:
      • GET /api/mails?subject=The subject (exact match)
      • GET /api/mails?subject=%subject% (contains)
    • Datetime: GET /api/mails?dateTimeSince=2020-12-06T10:00:00Z (ISO-8601 format)

• Delete sent mails DELETE /api/mails

  • Filter capabilities are included and can be combined:
    • To: DELETE /api/[email protected]

UI

• Retrieve sent mails and display them
• Delete sent mails

Extras

• Basic authentication support: Add basic authentication credentials by specifying environment variable AUTHENTICATION to the following format: user1:passwordForUser1;user2:passwordForUser2

• Request rate limiting: Both the actual SendGrid API server as well as the SSL server can be rate limited by specifying environment variables:

  • RATE_LIMIT_ENABLED: true or false (default)
  • RATE_LIMIT_WINDOW_IN_MS: The time window in milliseconds (default: 60000)
  • RATE_LIMIT_MAX_REQUESTS: The maximum number of requests allowed in the time window (default: 100)
  • SSL_RATE_LIMIT_ENABLED: true or false (default)
  • SSL_RATE_LIMIT_WINDOW_IN_MS: The time window in milliseconds (default: 60000)
  • SSL_RATE_LIMIT_MAX_REQUESTS: The maximum number of requests allowed in the time window (default: 100)

• By default, all emails older than 24 hours will be deleted. This can be configured using environment variable MAIL_HISTORY_DURATION which uses ISO-8601 Duration format such as 'PT24H'.

Dockerized

The SendGrid-Mock server and the UI are both contained in the same docker-image which you can pull from Docker Hub and start it via:

docker run -it -p 3000:3000 -e "API_KEY=sendgrid-api-key" ghashange/sendgrid-mock:1.9.2

Some prepared HTTP calls can be found here.

The UI can be accessed at http://localhost:3000.

SSL support

SendGrid-Mock also supports SSL using Let's Encrypt. To enable SSL, run it as follows:

docker run -it -p 3000:3000 -e "API_KEY=sendgrid-api-key" -e "CERT_DOMAINNAMES=[your-domain-name]" -e "CERT_EMAIL=[your-email-address]" ghashange/sendgrid-mock:1.9.2

Development

Setup with npm ci and start both server and UI concurrently with npm run dev. Per default the server is reachable via http://localhost:3000 and the UI via http://localhost:1234.

Some prepared HTTP calls can be found here.

The UI can be accessed at http://localhost:3000.

Build

Create docker image with docker build -t ghashange/sendgrid-mock:1.9.2 ..

Release

1. Update version number in package.json, version file and README

2. Create PR against master branch

3. Merge PR

4. Create GitHub release and update Docker Hub description

sendgrid-mock's Issues

Request - Helm chart for Sengrid mock

Hi @janjaali

I wanted to check with you if you would entertain a PR for a helm chart for sendgrid mock so that we can install sendgrid mock inside a kubernetes cluster.

We found the tool quite useful in our development and hence I would like to contribute a simple helm chart that we created. Please let me know. I should also be able to create readme on how to use the helm chart (and still support the env vars and configurations that your container expects)

Support for unsubscribe groups API

Hello! My team could have use for this project to do contract testing. One feature missing for us is support for the groups APIs (/v3/asm/groups). Would you be willing to look at a PR for the addition of these APIs to your mock server project? Thanks!

The API returns 200 even though the JSON is malformed

For example, when providing a JSON payload formed as follow:

{
   "from": "[email protected]"
}

instead of:

{
   "from": {
      "email": "[email protected]",
      "name": "Test"
   }
}

This SendGrid Mock will return a 200 response, an email will be stored in the docker image and it will be displayed in the UI with an empty "from" value.

The original SendGrid API however returns a 4XX response.
Would it be possible to mimic their error handling to get a mock as close as possible from the SendGrid API ?

[Question] - Sendgrid SDK

Hello, I was wondering if this project can be used with the Sendgrid Nodejs SDK?
Is there a way to redirect the emails being sent by the SDK to the docker container so they get captured?
Thanks!

attachments support

Would it be possible to add support for attachments? The ideal solution would allow any attachments added to the mail to be downloaded via the UI, but a lesser solution would just list the filenames of any included attachments.

[Question] - API Key

Hey there! Im trying to understand why the mock server needs an actual valid API key.
I tried using a non valid (but with right format) key and its giving me an authentication error so Im guessing it actually uses it for something.
I want to implement this on my development team but some people are concerned about sending our API Key to 3rd parties.
Thanks!

SyntaxError

I'm receiving a syntax error in the refactored code:

[HPM] Proxy created: /  ->  http://localhost:3000/api
/home/ronald/Projects/BringMe/utils/new-sendgrid-mock/src/server/handler/MailHandler.js:89
[0]   #mails = [];
[0]   ^
[0] 
[0] SyntaxError: Invalid or unexpected token
[0]     at Module._compile (internal/modules/cjs/loader.js:723:23)
[0]     at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)

Can't use template in send mail instead of content

Example http request body:

{
    "personalizations": [
        {
            "to": [
                {
                    "email": "[email protected]"
                },
                {
                    "email": "[email protected]"
                }
            ]
        }
    ],
    "from": {
        "email": "[email protected]"
    },
    "subject": "important subject",

    "dynamic_template_data": {
        "some_value": "1234",
        "some_other_value": "80202"
    },
    "template_id": "my-special-template"
}

This receives a 202 Accepted, but when we run the UI, it has a js error

Uncaught TypeError: Cannot read property 'map' of undefined
    at Cell (Mails.js:82)
    at mountIndeterminateComponent (react-dom.development.js:14811)
    at beginWork (react-dom.development.js:15316)
    at performUnitOfWork (react-dom.development.js:18150)
    at workLoop (react-dom.development.js:18190)
    at HTMLUnknownElement.callCallback (react-dom.development.js:149)
    at Object.invokeGuardedCallbackDev (react-dom.development.js:199)
    at invokeGuardedCallback (react-dom.development.js:256)
    at replayUnitOfWork (react-dom.development.js:17437)
    at renderRoot (react-dom.development.js:18309)

Broken SSL support

SSL usage broken due to wrongly used line endings while publishing docker image version.

Occurs in versions:

• 1.5.0
• 1.6.0
• 1.7.0

Fixed in 1.7.1 with #28.

Container crashes

Hi,

we're running this sendgrid-mock in Azure (using 1vCPU and 800MB of memory). We noticed that the container sometimes crashes (when under heavy load - so when a lot of emails are sent).

Did you also already saw this behavior? Is there anything we can do so it doesn't crash?

Add a button to the UI which deletes all emails

When clicked the button would call the endpoint
DELETE /api/mails

then fetch the mails again

Node version used for docker build and test can differ from each other

See #54 (comment).

SendGrid does not require 'content' field for templated emails

When I send our server's (working) sendgrid request (constructed via sendgrid's golang client API) to sendgrid-mock I see the following error:

{"errors":[{"field":"content","message":"must have required property 'content'","path":"#/required"}]}

Looking at the RequestHandler source:

I see

v3MailSend: {
    type: 'object',
    required: ['personalizations', 'content', 'from', 'subject'],

I also noticed that the template example in post-mail-template.http doesn't have a content field. Is this example working?

Apologies if I'm missing something obvious!

PR: SSL support

Hi,

would you be interested in a PR which adds SSL support using @appsaloon/auto-ssl?

Kind regards,
Ronald

x-message-id

Is it possible to add x-message-id to the response header for the POST (/mail/send) endpoint?
Explanation of that field is here: https://docs.sendgrid.com/glossary/what-is-x-message-id

crypto.randomUUID is not a function

After upgrading from v1.8.1 to v1.8.2, I get the following error in the container when processing an email request

TypeError: crypto.randomUUID is not a function
at /usr/src/server/src/server/ExpressApp.js:55:32
at Layer.handle [as handle_request] (/usr/src/server/node_modules/express/lib/router/layer.js:95:5)
at next (/usr/src/server/node_modules/express/lib/router/route.js:144:13)
at Route.dispatch (/usr/src/server/node_modules/express/lib/router/route.js:114:3)
at Layer.handle [as handle_request] (/usr/src/server/node_modules/express/lib/router/layer.js:95:5)
at /usr/src/server/node_modules/express/lib/router/index.js:284:15
at Function.process_params (/usr/src/server/node_modules/express/lib/router/index.js:346:12)
at next (/usr/src/server/node_modules/express/lib/router/index.js:280:10)
at /usr/src/server/node_modules/body-parser/lib/read.js:137:5
at AsyncResource.runInAsyncScope (async_hooks.js:198:9)

This causes a 500 response status code with the following body

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Error</title>
</head>
<body>
<pre>Internal Server Error</pre>
</body>
</html>

No such error occurs with v1.8.1.

Publish docker images with GitHub Actions

An essential part of SendGrid-Mock is the provision of a docker image containing both the UI and server.

Our "CI-pipeline" already checks for correct builds but ignores currently the Docker image creation itself. It would be helpful to integrate the Docker image creation in GitHub-Actions as well.

Sender behavior differs from SendGrid

Hello,

While trying out 1.9.0 I stumbled across the following: SendGrid API accepts some null values while the mock doesn't.

For example:
"from": { "email": "[email protected]", "name": null },
is accepted by SendGrid while the Mock complains about "name" not being a string value.

I haven't tested if that may be case for other properties but according to this documentation https://docs.sendgrid.com/api-reference/mail-send/errors, the name is optional in the model. I am using C# to call that API, and the name is nullable in my model, thus the JSON payload created contains null values.

Thanks !

LICENSE file

Hi, I see that your package.json state that the project is MIT licensed. But there's no LICENSE file to be found.

Can you add one to make others easier to use or contribute to your project? Or do you need me to create a pull request?
I didn't create a pull request because sensitive things like LICENSE are better done by the project owner.