Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/niiknow/email-bouncer-api
Simple email bounce handler/supression list
https://github.com/niiknow/email-bouncer-api
blacklist bounce email supression
Last synced: about 2 months ago
JSON representation
Simple email bounce handler/supression list
- Host: GitHub
- URL: https://github.com/niiknow/email-bouncer-api
- Owner: niiknow
- License: mit
- Created: 2018-12-28T08:38:56.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-01-13T02:05:31.000Z (about 1 year ago)
- Last Synced: 2024-04-14T06:10:44.650Z (9 months ago)
- Topics: blacklist, bounce, email, supression
- Language: PHP
- Size: 103 KB
- Stars: 3
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# email-bouncer-api
> A simple api to handle email bounces
# Features
- [x] hard bounce - block/blacklist almost permanently for (8^7 ~ approximately 4 years) minutes
- [x] soft bounce - block exponentially in multiple of 8^n, i.e. 8, 64, 512, 4096, etc... in minutes. Where n is the number of consecutive soft bounces. When soft bounce expired, it restart to 8 minutes
- [x] index - home endpoint can be use for healthcheck and also for cleanup of expired bounce with query string `/?purge=true`
- [x] handle SES->SNS webhook events
# Development
To run locally:
```
cp .env.example.ini .env.ini
composer install
php -S 0.0.0.0:8888 -t public
```
To run with docker:
```
cp .env.example.ini .env.ini
composer install
docker-compose up -d
```
Then visit: http://localhost:8888
Tip for composer in production, simply execute:
```
docker pull composer
docker run --rm --interactive --tty \
--volume $PWD:/app \
composer composer install --no-dev --optimize-autoloader
```
## API
### POST|GET /api/v1/bounces/[email protected]
> Record email as soft bounce - block similar to soft bounce
Complaint is in between a soft bounce and a hard bounce. It could be because the emailing System scan attachment and detect as a virus, or an actual User complaint with their email Provider.
### POST|GET /api/v1/bounces/[email protected]
> Record email as hard bounce - block for 1 year
### POST|GET /api/v1/bounces/[email protected],[email protected],[email protected]
> Bulk remove emails from bounce
### POST|GET /api/v1/bounces/[email protected]
> Record email as soft bounce - block incremental of 1 day
1. First soft bounce, block for 1 day
2. Second soft bounce within 1 day, block for 2 days
3. Third soft bounce within 2 day, block for 3 days
4. Forth soft bounce within 3 day, block for 4 days
5. And so on... up to 365 days max
### GET /api/v1/bounces/[email protected]
> Determine if email is sendable
Response:
```json
{
"throttle": "number of seconds before email is sendable, negative number implies email is sendable",
"sendable": true/false
}
```
This is probably the most common use method. Let say you want to send and email:
1. First, hit `/api/v1/bounces/[email protected]` to determine if you can send the email.
2. You don't have to parse the json, simply do `response.indexOf('true') > 0` to determine if you can send email.
3. Do not send email if check is not true.
**Note**: this response has a 20 minutes cache. This will help reduce the number of API calls when it is place behind some kind of a CDN (Content Delivery Network) Service.
### GET /api/v1/bounces/[email protected],[email protected],[email protected]
> Provide a list of emails to check
Result contain only emails that are found (previously bounced); if we do not have a record of the email, then it's probably sendable:
```json
{
"[email protected]": "number of seconds before email is sendable, negative number implies email is sendable",
"[email protected]": "same as above"
}
```
### GET /api/v1/bounces/aws-ses
> This endpoint is use for handling AWS SES->SNS subscription/webhook. See also - https://docs.aws.amazon.com/ses/latest/DeveloperGuide/event-publishing-retrieving-sns-examples.html
This feature makes it all worth it.
# Point of interest
Use this with [Haraka](https://haraka.github.io/) smtp server. I may create a Haraka plugin for this service.
# MIT