# Process with email verification queue Source: https://docs.usebouncer.com/api-reference/batch-sync/batch-sync post /v1.1/email/verify/batch/sync Synchronous Batch Email Verification API verifies one or multiple emails in a batch, offline manner. If you need to verify multiple email addresses in a batch, but you prefer synchronous integrations you can use our Synchronous Batch Email Verification API. Each request adds new emails to batch processing queue, and returns response when result is known. **Speed** Default settings allow our customers to verify 100k email addresses per hour, however if your use case requires higher throughput, please let us know and we will be able to adjust your configuration. **Rate Limiting** The Batch Sync Email Verification API is limited to 100 requests per minute by default. **Batch size recommendation** Single request can hold up to 10,000 emails. **Special considerations** Requests should be sent sequentially with delay between requests of 5sec to 10min. Results are kept up to 24h in Bouncer. After that delay email will be verified again and credits will be charged. # Create batch request Source: https://docs.usebouncer.com/api-reference/batch/batch-create post /v1.1/email/verify/batch Verifies one or multiple emails in a batch, offline manner. If you need to verify multiple email addresses in a batch, you can use our Batch Email Verification API. Bouncer distributed infrastructure will make sure to get best possible results and retry any verification in case one is required. For example: ```json theme={null} [ { "email": "jane@usebouncer.com"}, { "email": "john@usebouncer.com"} ] ``` Please make sure to store batchId as it will be necessary to check status and get results for the request. **Speed** Default settings allow our customers to verify 100-200k email addresses per hour, however if your use case requires higher throughput, please let us know and we will be able to adjust your configuration. **Rate Limiting** The Batch Email Verification API is limited to creating up to 60 batches per minute and 200 requests to other related endpoints. **Batch size recommendation** Single batch can process up to 100,000 emails, while recommended size would be anything between 1000-10000 emails. This method is recommended when the quality of verification is of a value as it characterises the best precision of email validation and the lowest possible amount of “unknown” results. **CSV format support** Batch can also be created using txt file, with one email per file, and then results downloaded as csv file. Example file content ```txt theme={null} deliverable@sandbox.usebouncer.com deliverable+2@sandbox.usebouncer.com deliverable+3@sandbox.usebouncer.com undeliverable@sandbox.usebouncer.com ``` ```bash theme={null} curl -v https://api.usebouncer.com/v1.1/email/verify/batch\?skip-header\=false \ --data-binary "@./test.csv" \ -H "x-api-key: " \ -H 'Content-Type: text/plain' ``` **Integration flow** There are 2 ways to integrate with batch, using status endpoint or using callback parameter. ***Using Status Endpoint*** ``` title Batch Integration Flow With Status Endpoint Client->>Bouncer: POST /v1.1/email/verify/batch loop every 10-30s until status == 'completed' Client->>Bouncer: GET /v1.1/email/verify/batch/ end Client->>Bouncer: GET /v1.1/email/verify/batch//download?download=all ``` ***Using Callbacks*** ``` title Batch Integration Flow With Callbacks Client->>Bouncer: POST /v1.1/email/verify/batch?callback= Bouncer->>Client: POST Client->>Bouncer: GET /v1.1/email/verify/batch//download?download=all ``` # Delete request Source: https://docs.usebouncer.com/api-reference/batch/batch-delete delete /v1.1/email/verify/batch/{batchId} Delete emails associated with request. Results will be lost. # Finish Source: https://docs.usebouncer.com/api-reference/batch/batch-finish post /v1.1/email/verify/batch/{batchId}/finish This endpoint will trigger internal job which will finish processing and return credits for remaining not verified emails. Results can be downloaded once status endpoint will return status "completed". # Get results Source: https://docs.usebouncer.com/api-reference/batch/batch-results get /v1.1/email/verify/batch/{batchId}/download Download batch result as JSON. You can filter out what to download by status, eg. download only deliverable emails. By default results are downloaded in JSON format. **CSV format support** Results can also be downloaded as CSV file by passing 'Accept' header. ```bash theme={null} curl https://api.usebouncer.com/v1.1/email/verify/batch//download \ -H "x-api-key: " \ -H 'Accept: text/csv' ``` # Check status Source: https://docs.usebouncer.com/api-reference/batch/batch-status get /v1.1/email/verify/batch/{batchId} Retrieve status of your request based on request id. Field "credits" will be filled with number of credits used once batch is complete. Additional query parameter "with-stats=true" will add to the response processing progress and statistics. ```json theme={null} { "batchId": "642152127eec9c46c00fb8d7", "created": "2023-03-27T08:21:38.357Z", "started": "2023-03-27T08:21:40.355Z", "completed": "2023-03-27T08:21:51.426Z", "status": "completed", "quantity": 2, "duplicates": 0, "credits": 2, "processed": 2, "stats": { "deliverable": 1, "risky": 0, "undeliverable": 1, "unknown": 0 } } ``` # Check available credits Source: https://docs.usebouncer.com/api-reference/credits/credits get /v1.1/credits Retrieve available credits. **Rate Limiting** Limit of 10 requests per minute is available. # Verify domain Source: https://docs.usebouncer.com/api-reference/domain/verify-domain get /v1.1/domain Verifies single domain. You can use Bouncer’s Domain Verification API to check domain information. It can be usefull to verify is domain has valid MX records and if it behaves as a "catch all" domain. One credit will be charged. **Rate Limiting** Domain Verification API is limited to 1000 requests per minute by default. # Verify email Source: https://docs.usebouncer.com/api-reference/real-time/verify-email get /v1.1/email/verify Verifies single email in real-time synchronous manner. You can use Bouncer’s Real-time Email Verification API to check email addresses at the moment of entry, and implement it for your sign up forms. It is a full email verification and email validation method – it not only checks the syntax and domain of the address but also contacts underlying SMTP servers to check deliverability of email addresses. Bouncer will return the best possible results that it will be able to gather within 10 seconds (maximum 30). This method is recommended when speed of verification is of a value as usually this method returns 5% more “unknown” results than full integration using Batch Email Verification API. **Rate Limiting** Real-Time Email Verification API is limited to 1000 requests per minute by default. Higher limit can be configured in special cases. **Retry After** In cases when we may provide results after greylisting additional parameter "retryAfter" will be added. # Create toxicity list job Source: https://docs.usebouncer.com/api-reference/toxicity/toxicity-create post /v1/toxicity/list **Rate Limiting** API allows creating of 10 lists per minute. # Delete toxicity list job Source: https://docs.usebouncer.com/api-reference/toxicity/toxicity-delete delete /v1/toxicity/list/{id} # Download toxicity list results Source: https://docs.usebouncer.com/api-reference/toxicity/toxicity-results get /v1/toxicity/list/{id}/data # Check toxicity list job status Source: https://docs.usebouncer.com/api-reference/toxicity/toxicity-status get /v1/toxicity/list/{id} # Integration Guidelines Source: https://docs.usebouncer.com/integration-guidelines ## Which API should I choose? ### Real-Time Real-Time API endpoint should be used when response time is crucial. It is easiest to use, but has some drawbacks which make it unsuitable to verify large databases. Rate limit limits number of emails that can be verified per hour. Some emails require retries or long SMTP connections taking over 40 seconds which causes more unknown results. [API Reference](/api-reference/real-time/verify-email) ### Batch Bouncer can process maximum volume of emails using this API. Implementation is a bit more complicated than using Real-Time API though. Integration flow in pseudocode. ```javascript theme={null} // psuedocode while(true) { // check status of active batches (created and not completed) var batchesActive = getActiveBatches(); // create batches if (batchesActive.size() < 10) { // create batch if needed var emailsToVerify = prepareBatchOfEmailsToVerify(); if (emailsToVerify.size() > 0) { try { var batchStatus = bouncer.batchCreate(emailToVerify); storeBatchInformation(batchStatus.batchId, 'active'); } catch(error) { // handle special cases (payment required, rate limit, 5XX errors) } } } // check status and download results batchesActive.forEach(batch => { var batchStatus = bouncer.batchStatus(batch.batchId); if (batchStatus.status === 'completed') { // download results var batchResults = bouncer.batchResults(batch.batchId); storeBatchResults(batch.batchId, batchResults); storeBatchInformation(batch.batchId, 'done') } }); sleepSeconds(10); } ``` Considerations: * batches are processed sequentially, so when batch with 100000 emails is sent next batch with 1000 emails will have to wait ### Batch/Sync This API is similar to Batch API, with some additional features: * there is no need to remember batch id * internal queue is kept internally * there is no need for batch to finish to get some of the results * it keeps 24h cache, so it doesn't verify the same email multiple times in this timeframe Best way to implement integration using batch/sync endpoint, would be to create a queue of emails to be verified. In some kind of pseudocode it would look like this. ```javascript theme={null} // psuedocode while(true) { var emailsToVerify = sql('select email from queue where result == null order by queuedAt limit 10000'); if (emailsToVerify.size() == 0) { sleepSeconds(10); } try { var results = bouncer.batchSync(emailToVerify); updateQueueWithResults(results); sleepSeconds(3); } catch(error) { // handle special cases (payment required, rate limit, 5XX errors) } } ``` ## Implementation ### Implement Bouncer API Client #### SDK When using Java as your programming language our client library can be used. [https://github.com/bouncer-admin/bouncer-java-sdk](https://github.com/bouncer-admin/bouncer-java-sdk) It can be used as is, or modified to match your tech stack and dependencies. #### Encoding When using real-time * make sure that '+' is encoded properly otherwise bouncer will receive '[test+123@usebouncer.com](mailto:test+123@usebouncer.com)' as 'test [123@usebouncer.com](mailto:123@usebouncer.com)' and return undeliverable invalid\_email When using batch * '' is a special character in json and "[deliverable+6@sandbox.usebouncer.com](mailto:deliverable+6@sandbox.usebouncer.com)" is not a valid json value ### Error Handling The API makes use of standard HTTP errors to indicate the success or failure of a request. The 2xx series of response codes indicate a success, 4xx indicates an error from the client side, and a 5xx error indicates a server-side error. Here are the HTTP response codes the API utilises: * 200 Success * 400 Bad Request * 401 Unauthorized * 402 Payment Required * 403 Forbidden * 404 Not Found * 429 Too Many Requests * 503 Service Unavailable #### Cases to handle while implementing integration: * Status code 402 - Account does not have enough credits to handle request. Purchase is required. Other way to handle this is to configure email alerts or auto-refill available with subscription. * Status code 429 - Request have been rate limited. Too many requests have been sent. * Status code 503 - In some edge cases it's possible that response with status code 503 will be returned. In that case retry should solve the problem. ## How to interpret results? In different use cases different rules may be applied to decide which emails should be kept or removed. Keep: * status deliverable * if your deliverability is not impacted and list is relatively clean * status risky and flag domain.acceptAll "yes" * status unknown with reasons unknown, timeout, unsupported Remove/Suppress: * status undeliverable * toxicity with values 4 and 5 (they may impact your sending infrastructure reputation) * status risky with flag account.fullMailbox "yes" Description of all datapoints is available on [Terminology](/terminology) page. # Bouncer Source: https://docs.usebouncer.com/introduction Bouncer Email Verification API lets you validate email address and verify its deliverability, in the way you want. It’s easy to integrate, powerful, robust, secure, ultrafast and affordable. ```json theme={null} { "email": "hello@usebouncer.com", "status": "deliverable", "reason": "accepted_email", "domain": { "name": "usebouncer.com", "acceptAll": "no", "disposable": "no", "free": "no" }, "account": { "role": "yes", "disabled": "no", "fullMailbox": "no" }, "dns": { "type": "MX", "record": "aspmx.l.google.com." }, "provider": "google.com", "score": 100, "toxic": "unknown", "toxicity": 0 } ``` Let Bouncer handle verification and validation of your email addresses, with Real-Time (synchronous), Batch (asynchronous), and a hybrid of those two Batch Synchronous end-points. ## Where to start? [Quick Start](/quick-start) [Integration Guidelines](/integration-guidelines) [API Reference](/api-reference/real-time/verify-email) If at any time you would need extra support from our side, you can reach us by email at : [support@usebouncer.com](mailto:support@usebouncer.com) # Quick Start Source: https://docs.usebouncer.com/quick-start ## Authentication All calls made to the Bouncer API have to be made using HTTPS. In order to generate your API Key go [here](https://app.usebouncer.com/signup) or: * sign up for a Bouncer account [here](https://app.usebouncer.com/login), * click on the API on the left-site menu, * click Generate API Key button. Bouncer API supports 2 methods of authentication: ### x-api-key in header ```bash theme={null} curl https://api.usebouncer.com/v1.1/email/verify?email=john@usebouncer.com \ -H 'x-api-key: API-KEY' ``` ### "Basic" authentication with api key as password ```bash theme={null} curl https://api.usebouncer.com/v1.1/email/verify?email=john@usebouncer.com \ -u :API-KEY ``` ## API Reference Interactive API Reference can be used to send first requests. [API Reference](/api-reference/real-time/verify-email) ## Test Data Sandbox emails can be used free of charge during implementation of integration. [Sandbox](/sandbox) ## Integration Guidelines For more comprehensive integration guidelines please read [Integration Guidelines](/integration-guidelines). # null Source: https://docs.usebouncer.com/sandbox Emails that can be used free of charge: * [deliverable@sandbox.usebouncer.com](mailto:deliverable@sandbox.usebouncer.com) * [free@sandbox.usebouncer.com](mailto:free@sandbox.usebouncer.com) * [disposable@sandbox.usebouncer.com](mailto:disposable@sandbox.usebouncer.com) * [accept-all@sandbox.usebouncer.com](mailto:accept-all@sandbox.usebouncer.com) * [undeliverable@sandbox.usebouncer.com](mailto:undeliverable@sandbox.usebouncer.com) * [unknown@sandbox.usebouncer.com](mailto:unknown@sandbox.usebouncer.com) * [other@sandbox.usebouncer.com](mailto:other@sandbox.usebouncer.com) Any of them can be modified with a "+" suffix to generate more unique emails. For example: * [deliverable+12345@sandbox.usebouncer.com](mailto:deliverable+12345@sandbox.usebouncer.com) # Terminology Source: https://docs.usebouncer.com/terminology ```json theme={null} { "email": "hello@usebouncer.com", "status": "deliverable", "reason": "accepted_email", "domain": { "name": "usebouncer.com", "acceptAll": "no", "disposable": "no", "free": "no" }, "account": { "role": "yes", "disabled": "no", "fullMailbox": "no" }, "dns": { "type": "MX", "record": "aspmx.l.google.com." }, "provider": "google.com", "score": 100, "toxic": "unknown", "toxicity": 0 } ``` ## Statuses Every email address that you verify, will come back with a result that is either 'deliverable', 'undeliverable', 'risky' or 'unknown'. Below is a short explanation of what each means: * `deliverable` - The recipient's email provider has confirmed that the email address exists, it is safe to send. * `risky` - The email address may result in a bounce or low engagement. Risky addresses: Accept All, Full Mailbox or Disposable. * `undeliverable` - The address is either syntactically incorrect or does not exist. * `unknown` - We were unable to receive a response from the email provider. ## Reasons Additionally to the status of your results, Bouncer will provide you with a reason for the results: ### risky * `low_deliverability` - Email address appears to be deliverable, but deliverability cannot be guaranteed (in most cases it is caused by catch\_all / accept\_all configuration of recipient’s server or full mailbox). * `low_quality` - Email address has quality issues that may make it a risky or low-value address (in most cases it is caused by the fact that it is a disposable/temporary email). ### undeliverable * `invalid_email` - Specified email doesn't have a valid email address syntax. * `invalid_domain` - Domain for email does not exist or has no valid DNS records. * `rejected_email` - Email address was rejected by the SMTP server, email address does not exist. ### unknown * `dns_error` - We were unable to resolve DNS records or domain is misconfigured. * `unavailable_smtp` - SMTP server was unavailable to process our request. * `unsupported` - Email hosted by an unsupported email service provider. * `timeout` - Verification required more time than was available. * `unknown` - An unexpected error has occurred. ## Domain Bouncer also provides some information about the domain of the email address: ### name Domain of the email. ## acceptAll Is domain configured to accept all emails? * `yes` - Domain of the email address is configured to accept all /catch all the emails. * `no` - Domain of the email address does not accept all emails. * `unknown` - Bouncer was unable to check if the domain of the email address is configured to accept all / catch all the emails. ### disposable Is domain known disposable / temporary email provider? * `yes` - Email address is hosted by a known disposable / temporary email provider. * `no` - Email address is not hosted by a known disposable / temporary email provider. * `unknown` - Bouncer was unable to check if the email is a deposable / temporary email address. ### free Is domain known free email provider? * `yes` - Email address is hosted by a known free email provider. * `no` - Email address is not hosted by a known free email provider. * `unknown` - Bouncer was unable to check if the email is a free email address. ## Account Bouncer also provides some information about the email account itself: ### role Is the email address a role / functional one (like support, hello, etc.)? * `yes` - Email address is associated with a function. * `no` - Email address is not associated with a function. * `unknown` - Bouncer was unable to check if the email address is a role / functional one. ### disabled Is the account disabled? * `yes` - Account is disabled. * `no` - Account is not disabled. * `unknown` - Bouncer was unable to check if the account is disabled. ### fullMailbox Is the mailbox full? * `yes` - Mailbox is full. * `no` - Mailbox is not full. * `unknown` - Bouncer was unable to check if the mailbox is full. ## Provider Name of infrastructure provider which handles SMTP communication for this domain. It can be either an email service provider or a name of an anti-spam filter provider which protects underlying infrastructure. ## DNS * type: `MX` - domain does have MX records configured * type: `A` - only A records were found * `record` - dns record used for verification ## Did You Mean If the email address you have provided seems to be undeliverable or of low quality - Bouncer may find a suggestion of a correct one and return it in the didYouMean field. Please note it was not fully verified, so you might want to run a verification of the suggested email address. ## Score Score represents chance for successful delivery of email. 100 means 100% chance of delivery, given sending infrastructure has good reputation. Empty value means that it wouldn't make sense to evaluate score, for example in the case of timeout.