Provides a service that simulates the sending mail endpoint provided by SendGrid API that may only be used for development purposes.
It contains a simple UI where you can:
- list received mails, filtering by recipient and subject, with pagination;
- view the HTML, text or raw HTML content of a mail;
- list and download attachments;
- delete a single mail or all of them;
- switch between light, dark or automatic theme.
POST /v3/mail/send: SendGrid like sending mail endpoint- Requires the
Authorization: Bearer <API_KEY>header - The request body is validated against the SendGrid mail send schema
- Returns
202 Acceptedwith theX-Message-Idheader
- Requires the
GET /messages: search persisted messages- Query parameters:
to: filter by to address (accepts%wildcard)subject: filter by subject (accepts%wildcard)page: paginate results starting from0rows: number of rows returned on each page (default10)
- Query parameters:
GET /messages/:event_id: return message content- Path parameter:
event_id: event identifier
- Query parameter:
format: must be one of:html: rendered HTML, with links rewritten to track clickstext: plain text contentraw: original HTML source, returned as plain text
- Path parameter:
GET /messages/:event_id/attachments/:filename: download an attachment- Path parameters:
event_id: event identifierfilename: attachment file name
- Path parameters:
GET /messages/:event_id/links/:encoded_link: track a click and redirect to the decoded link (used by the rendered HTML content)DELETE /messages/:event_id: delete message- Path parameter:
event_id: event identifier
- Path parameter:
DELETE /messages: delete all messagesGET /health: health check
Errors are returned as JSON describing the failed field, the reason and a hint on how to fix it.
There is a basic support for events, currently sending (when enabled) one of these events:
- delivered: when the message was persisted in the database;
- dropped: when some failure occurs when persisting in the database;
- open: when mail content is retrieved through the
GET /messages/:event_idendpoint; - click: when a link is clicked in the rendered content;
Each event includes the message custom_args and categories.
There are some customization possibles, all of them are defined by using the system environment.
- API_KEY: Used to authenticate the sending mail endpoint, defaults to
mock.luPzMYLzMTWJqMLCO37ZJRmPllQ7ct78; - EVENT_DELIVERY_URL: when defined, it used for event sending;
- MAIL_HISTORY_DURATION: duration, using Golang pattern, which is used to delete messages older than that duration,
defaults to
24h; - STORAGE_FILE: when defined, instead of creating a randomized temporary file, the given file name will be used;
- BLOCK_DELETE_ALL: when value is
true, deleting all messages will not be allowed; - EVENT_TIMESTAMP_DELAY: duration, using Golang pattern, which is used to add extra time to the events;
- WEB_STATIC_FILES: directory with the UI static files, defaults to
./web/;
The service listens on port 3000.
docker run -p 3000:3000 --rm ghcr.io/rapatao/sendgrid-mock:${version:-latest}Requires Go and a C compiler (CGO is used by SQLite).
make runcurl -X POST "http://localhost:3000/v3/mail/send" \
-H "Authorization: Bearer mock.luPzMYLzMTWJqMLCO37ZJRmPllQ7ct78" \
-H "Content-Type: application/json" \
--data '{"personalizations": [{"to": [{"email": "alex@example.com"}]}], "from": {"email": "orders@example.com"}, "subject": "Hello", "content": [{"type": "text/html", "value": "<p>Hello!</p>"}]}'More examples are available in the scripts directory.
This service/repository should not be used as a studying reference since it isn't using good development practices and has limited test coverage. It was built with the intention to provide a service that should be used for development purposes only.
