{"id":22245473,"url":"https://github.com/niiknow/email-bouncer-api","last_synced_at":"2026-02-22T02:33:08.491Z","repository":{"id":83312616,"uuid":"163387489","full_name":"niiknow/email-bouncer-api","owner":"niiknow","description":"Simple email bounce handler/supression list","archived":false,"fork":false,"pushed_at":"2024-01-13T02:05:31.000Z","size":105,"stargazers_count":4,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-04T12:35:42.742Z","etag":null,"topics":["blacklist","bounce","email","supression"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niiknow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-28T08:38:56.000Z","updated_at":"2025-03-17T23:46:53.000Z","dependencies_parsed_at":"2023-12-27T06:33:35.191Z","dependency_job_id":"55e69572-94ef-4830-9415-6143e0ed1cc0","html_url":"https://github.com/niiknow/email-bouncer-api","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/niiknow/email-bouncer-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Femail-bouncer-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Femail-bouncer-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Femail-bouncer-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Femail-bouncer-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niiknow","download_url":"https://codeload.github.com/niiknow/email-bouncer-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Femail-bouncer-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267453979,"owners_count":24089854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blacklist","bounce","email","supression"],"created_at":"2024-12-03T05:15:24.534Z","updated_at":"2025-10-06T17:16:36.860Z","avatar_url":"https://github.com/niiknow.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# email-bouncer-api\n\u003e A simple api to handle email bounces\n\n# Features\n- [x] hard bounce - block/blacklist almost permanently for (8^7 ~ approximately 4 years) minutes\n- [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\n- [x] index - home endpoint can be use for healthcheck and also for cleanup of expired bounce with query string `/?purge=true`\n- [x] handle SES-\u003eSNS webhook events\n\n# Development\n\nTo run locally:\n```\ncp .env.example.ini .env.ini\ncomposer install\nphp -S 0.0.0.0:8888 -t public\n```\n\nTo run with docker:\n```\ncp .env.example.ini .env.ini\ncomposer install\ndocker-compose up -d\n```\n\nThen visit: http://localhost:8888\n\nTip for composer in production, simply execute:\n```\ndocker pull composer\ndocker run --rm --interactive --tty \\\n  --volume $PWD:/app \\\n  composer composer install --no-dev --optimize-autoloader\n```\n\n## API\n\n### POST|GET /api/v1/bounces/complaint?email=a-valid@email.com\n\u003e Record email as soft bounce - block similar to soft bounce\n\nComplaint 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.\n\n### POST|GET /api/v1/bounces/hard?email=a-valid@email.com\n\u003e Record email as hard bounce - block for 1 year\n\n### POST|GET /api/v1/bounces/remove?emails=a-invalid@email.com,b-invalid@email.net,c-invalid@email.org\n\u003e Bulk remove emails from bounce\n\n### POST|GET /api/v1/bounces/soft?email=a-valid@email.com\n\u003e Record email as soft bounce - block incremental of 1 day\n\n1. First soft bounce, block for 1 day\n2. Second soft bounce within 1 day, block for 2 days\n3. Third soft bounce within 2 day, block for 3 days\n4. Forth soft bounce within 3 day, block for 4 days\n5. And so on... up to 365 days max\n\n### GET /api/v1/bounces/stat?email=a-valid@email.com\n\u003e Determine if email is sendable\n\nResponse:\n```json\n{\n   \"throttle\": \"number of seconds before email is sendable, negative number implies email is sendable\",\n   \"sendable\": true/false\n}\n\n```\n\nThis is probably the most common use method.  Let say you want to send and email:\n1. First, hit `/api/v1/bounces/stat?email=a-valid@email.com` to determine if you can send the email.\n2. You don't have to parse the json, simply do `response.indexOf('true') \u003e 0` to determine if you can send email.\n3. Do not send email if check is not true.\n\n**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.\n\n### GET /api/v1/bounces/stats?emails=a-invalid@email.com,b-invalid@email.net,c-invalid@email.org\n\u003e Provide a list of emails to check\n\nResult contain only emails that are found (previously bounced); if we do not have a record of the email, then it's probably sendable:\n```json\n{\n   \"a-invalid@email.com\": \"number of seconds before email is sendable, negative number implies email is sendable\",\n   \"b-invalid@email.net\": \"same as above\"\n}\n```\n\n### GET /api/v1/bounces/aws-ses\n\u003e This endpoint is use for handling AWS SES-\u003eSNS subscription/webhook.  See also - https://docs.aws.amazon.com/ses/latest/DeveloperGuide/event-publishing-retrieving-sns-examples.html \n\nThis feature makes it all worth it.\n\n# Point of interest\nUse this with [Haraka](https://haraka.github.io/) smtp server.  I may create a Haraka plugin for this service.\n\n# MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniiknow%2Femail-bouncer-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniiknow%2Femail-bouncer-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniiknow%2Femail-bouncer-api/lists"}