Skip to content

Commit

Permalink
Updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
andris9 committed Sep 5, 2024
1 parent 01f1dae commit 9669e40
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 60 deletions.
117 changes: 58 additions & 59 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,136 +1,135 @@
![logo](https://raw.githubusercontent.com/postalsys/emailengine/master/static/logo/EmailEngine_logo_vert.png)
![EmailEngine Logo](https://raw.githubusercontent.com/postalsys/emailengine/master/static/logo/EmailEngine_logo_vert.png)

# EmailEngine Email API

Headless email client application that makes IMAP and SMTP, Gmail API, and MS Graph API resources available over an unified REST API. Integrate email accounts with your service with ease!
A headless email client application that provides access to IMAP, SMTP, Gmail API, and MS Graph API resources via a unified REST API. Easily integrate email accounts with your service!

- Documentation and details: [EmailEngine.app](https://emailengine.app/)
- Full documentation: [EmailEngine.app](https://emailengine.app/)

## Use cases
## Use Cases

- Syncing users' emails to your service and sending out emails on behalf of your users
- Integrating your app with a specific email account, eg. your support email
- [Monitor INBOX and Junk folders](https://docs.emailengine.app/measuging-inbox-spam-placement/) of a test email account to see where the emails you send out end up in
- Lightweight webmail and mobile email apps that do not want to process IMAP and MIME
- Sync users' emails with your service and send emails on their behalf.
- Integrate your app with a dedicated email account, such as your support email.
- [Monitor INBOX and Junk folders](https://docs.emailengine.app/measuging-inbox-spam-placement/) of a test email account to track where sent emails land.
- Ideal for lightweight webmail and mobile email apps that prefer to avoid direct IMAP and MIME processing.

## Quickstart

- [Set-up instructions](https://emailengine.app/set-up)
- [Setup Instructions](https://emailengine.app/set-up)

## Screenshots

![](https://cldup.com/dC_4_suWrh.png)
![Screenshot 1](https://cldup.com/dC_4_suWrh.png)
![Screenshot 2](https://cldup.com/KibGXRw8Mm.png)
![Screenshot 3](https://cldup.com/mCxzWWjcLL.png)

![](https://cldup.com/KibGXRw8Mm.png)
## Version and License

![](https://cldup.com/mCxzWWjcLL.png)
Run the following command to check the version and license information for both EmailEngine and its included modules:

## Version and license

Run the following command to see the version and license information both for EmailEngine and for the included modules.

```
```bash
$ emailengine license
```

## Requirements

- **Redis**any version
- **Redis**Any version

There is no official [Redis](https://redis.io/) release for Windows but you can use an alternative like [Memurai](https://www.memurai.com/).
> [!NOTE]
> While Redis does not officially support Windows, alternatives like [Memurai](https://www.memurai.com/) are available.
> **Tip!** Try to keep the latency between EmailEngine and Redis as low as possible, best if these would run in the same machine or at least in the same DC. EmailEngine runs a separate Redis command for each message in a folder when syncing messages, so if the latency is not low then it takes a long time to sync a folder with a lot of messages,
> [!TIP]
> Minimize the latency between EmailEngine and Redis by running both on the same machine or in the same data center. Since EmailEngine runs a separate Redis command for each message in a folder during syncing, high latency can lead to slow sync times for folders with many messages.
## Documentation

- [API Reference](https://api.emailengine.app/)
- [Blog posts](https://docs.emailengine.app/tag/email-engine/)
- For Postman you can import OpenAPI specification [here](https://api.emailengine.app/swagger.json).
- [Blog Posts](https://docs.emailengine.app/tag/email-engine/)
- OpenAPI specification for Postman: [Swagger.json](https://api.emailengine.app/swagger.json)

## Configuring EmailEngine

See the documentation for configuring EmailEngine [here](https://emailengine.app/configuration).
Refer to the [configuration documentation](https://emailengine.app/configuration) for details on setting up EmailEngine.

## App access
## App Access

By default EmailEngine allows connections only from localhost. To change this either edit config file or use `--api.host="0.0.0.0"` cli option. This would enable outside access, so you should use firewall or a proxy to only allow trusted sources.
By default, EmailEngine only allows connections from localhost. To enable external access, either edit the config file or use the CLI option `--api.host="0.0.0.0"`. Ensure to secure external access with a firewall or proxy to allow only trusted sources.

## Deployment

### Ubuntu or Debian

You can use the included install script to set up
You can use the included install script to set up:

- EmailEngine as a SystemD service
- Caddy as a reverse proxy and HTTPS certificate handler

```
```bash
$ wget https://raw.githubusercontent.com/postalsys/emailengine/master/install.sh
$ chmod +x install.sh
$ ./install.sh example.com
```

Where

- **example.com** is the domain name for EmailEngine
Where **example.com** is the domain name for EmailEngine.

> **NB!** Tested with Ubuntu 20.04 and Debian 11. Might not work with other OS versions.
> [!NOTE]
> Tested on Ubuntu 20.04 and Debian 11. Other versions may not be supported.
### SystemD

Read about running EmailEngine as a SystemD service [here](https://emailengine.app/system-d-service)
Learn more about running EmailEngine as a SystemD service [here](https://emailengine.app/system-d-service).

### Docker

![Docker Image Size (tag)](https://img.shields.io/docker/image-size/postalsys/emailengine/v2?label=Docker%20image%20size)
![Docker Image Size](https://img.shields.io/docker/image-size/postalsys/emailengine/v2?label=Docker%20image%20size)

To execute EmailEngine-CLI commands while using the Docker Container, you can use the following approach:
To execute EmailEngine-CLI commands within a Docker container:

1. Exec into the Docker Container:
1. Exec into the container:

```
$ docker exec -it <container-id> /bin/sh
```
```bash
$ docker exec -it <container-id> /bin/sh
```

2. Run the command by executing the `./bin/emailengine.js` file with node:
2. Run commands using `./bin/emailengine.js`:

```
$ node bin/emailengine.js <command>
```
```bash
$ node bin/emailengine.js <command>
```

See the full documentation for using EmailEngine with Docker [here](https://emailengine.app/docker).
For full Docker usage documentation, visit [here](https://emailengine.app/docker).

## Resolving issues with Redis
## Resolving Issues with Redis

EmailEngine is using Redis as it's data store. Redis stores everything in RAM so if something weird happens, EmailEngine could flood Redis and make the app unusable once there is no available space left.
EmailEngine relies on Redis as its data store. Redis stores everything in RAM, so if an issue arises, EmailEngine may flood Redis, rendering the app unusable if space runs out.

First thing to do is to check what is actually going on. EmailEngine provides a few tools for that:
To diagnose problems:

1. Check Bull queues in Redis. You can use the built in Bull Arena UI to view the state of the queues. Open [http://127.0.0.1:3000/admin/arena](http://127.0.0.1:3000/admin/arena) in your browser to see the queues.
2. Scan the used keyspace. EmailEngine provides a tool that groups keys by type. Run it like this (use the same config for DB as you are using for the main app):
1. **Check Bull Queues:** Use the built-in Bull Arena UI to monitor queue states at [http://127.0.0.1:3000/admin/arena](http://127.0.0.1:3000/admin/arena).
2. **Scan Keyspace:** Run the following to group Redis keys by type and generate a report:

```
$ emailengine scan > keyspace.csv
```
```bash
$ emailengine scan > keyspace.csv
```

## Monitoring

There is a Prometheus output available at `/metrics` URL path of the app.
EmailEngine provides Prometheus metrics, available at the `/metrics` URL path.

## Log analysis
## Log Analysis

Read about logging options [here](https://emailengine.app/logging)
For information on logging options, read the documentation [here](https://emailengine.app/logging).

To start EmailEngine to trail the IMAP traffic of a specific account
To trace IMAP traffic for a specific account, use the following command:

```
```bash
$ npm run raw -- --filter.account=account1
```

## Security and Data compliance
## Security and Data Compliance

[Read here](https://docs.emailengine.app/data-compliance/).
For detailed security and data compliance information, refer to [this guide](https://docs.emailengine.app/data-compliance/).

## Licensing

Licensed under the commercial [EmailEngine License](./LICENSE_EMAILENGINE.txt).
EmailEngine is licensed under the commercial [EmailEngine License](./LICENSE_EMAILENGINE.txt).
2 changes: 1 addition & 1 deletion winconf.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ const options = {
version: PackageData.version,
properties: {
LegalCopyright: 'Postal Systems OÜ',
FileDescription: 'EmailEngine allows access to email accounts using REST',
FileDescription: 'EmailEngine allows access to email accounts using REST API',
ProductName: 'EmailEngine'
},
icon: 'static/emailengine.ico'
Expand Down

0 comments on commit 9669e40

Please sign in to comment.