# Emailable Python Library
[](https://pypi.org/project/emailable/)
[](https://codeclimate.com/github/emailable/emailable-python/maintainability)
This is the official python wrapper for the Emailable API.
## Documentation
See the [Python API docs](https://emailable.com/docs/api/?python).
## Installation
```shell
pip install emailable
```
## Usage
The library needs to be configured with your account's API key which is available in your [Emailable Dashboard](https://app.emailable.com/api).
### Setup
```python
import emailable
client = emailable.Client('live_...')
```
### Verification
```python
# verify an email address
response = client.verify('evan@emailable.com')
response.state
=> 'deliverable'
# additional parameters are available. see API docs for additional info.
client.verify('evan@emailable.com', smtp=False, accept_all=True, timeout=25)
```
#### Slow Email Server Handling
Some email servers are slow to respond. As a result, the timeout may be reached
before we are able to complete the verification process. If this happens, the
verification will continue in the background on our servers. We recommend
sleeping for at least one second and trying your request again. Re-requesting
the same verification with the same options will not impact your credit
allocation within a 5 minute window.
A slow response will return with a 249 status code.
```python
response = client.verify('slow@example.com')
response.status_code
=> 249
response.message
=> 'Your request is taking longer than normal. Please send your request again.'
```
### Batch Verification
#### Start a batch
```python
emails = ['evan@emailable.com', 'support@emailable.com', ...]
response = client.batch(emails)
response.id
=> '5cff27400000000000000000'
# you can optionally pass in a callback url that we'll POST to when the
# batch is complete.
response = client.batch(emails, {'url': 'https://emailable.com/'})
```
#### Get the status / results of a batch
To get the status of a batch call `batch_status` with the batch's id. If your batch is still being processed, you will receive a message along with the current progress of the batch. When a batch is completed, you can access the results in the `emails` attribute.
```python
response = client.batch_status('5cff27400000000000000000')
# if your batch is still running
response.processed
=> 1
response.total
=> 2
response.message
=> 'Your batch is being processed.'
# if your batch is complete
response.emails
=> [{'email': 'evan@emailable.com', 'state': 'deliverable'...}, {'email': 'support@emailable.com', 'state': 'deliverable'...}...]
# get the counts
response.total_counts
=>{'deliverable': 2, 'undeliverable': 0 ...}
response.reason_counts
=>{'accepted_email': 2, 'rejected_email': 0 ...}
```
## Development
Tests can be run with the following command:
```shell
pytest
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/emailable/emailable-python.
Raw data
{
"_id": null,
"home_page": "https://github.com/emailable/emailable-python",
"name": "emailable",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "emailable email verification",
"author": "Emailable",
"author_email": "support@emailable.com",
"download_url": "https://files.pythonhosted.org/packages/53/42/45f5a7ca51261c2189bb4ebe48c6c081b040b40dd92a72fec90f3dc4c912/emailable-3.0.2.tar.gz",
"platform": null,
"description": "# Emailable Python Library\n\n[](https://pypi.org/project/emailable/)\n\n[](https://codeclimate.com/github/emailable/emailable-python/maintainability)\n\nThis is the official python wrapper for the Emailable API.\n\n## Documentation\n\nSee the [Python API docs](https://emailable.com/docs/api/?python).\n\n## Installation\n\n```shell\npip install emailable\n```\n\n## Usage\n\nThe library needs to be configured with your account's API key which is available in your [Emailable Dashboard](https://app.emailable.com/api).\n\n### Setup\n\n```python\nimport emailable\n\nclient = emailable.Client('live_...')\n```\n\n### Verification\n\n```python\n# verify an email address\nresponse = client.verify('evan@emailable.com')\nresponse.state\n=> 'deliverable'\n\n# additional parameters are available. see API docs for additional info.\nclient.verify('evan@emailable.com', smtp=False, accept_all=True, timeout=25)\n```\n\n#### Slow Email Server Handling\n\nSome email servers are slow to respond. As a result, the timeout may be reached\nbefore we are able to complete the verification process. If this happens, the\nverification will continue in the background on our servers. We recommend\nsleeping for at least one second and trying your request again. Re-requesting\nthe same verification with the same options will not impact your credit\nallocation within a 5 minute window.\n\nA slow response will return with a 249 status code.\n\n```python\nresponse = client.verify('slow@example.com')\nresponse.status_code\n=> 249\nresponse.message\n=> 'Your request is taking longer than normal. Please send your request again.'\n```\n\n### Batch Verification\n\n#### Start a batch\n\n```python\nemails = ['evan@emailable.com', 'support@emailable.com', ...]\nresponse = client.batch(emails)\nresponse.id\n=> '5cff27400000000000000000'\n\n# you can optionally pass in a callback url that we'll POST to when the\n# batch is complete.\nresponse = client.batch(emails, {'url': 'https://emailable.com/'})\n```\n\n#### Get the status / results of a batch\n\nTo get the status of a batch call `batch_status` with the batch's id. If your batch is still being processed, you will receive a message along with the current progress of the batch. When a batch is completed, you can access the results in the `emails` attribute.\n\n```python\nresponse = client.batch_status('5cff27400000000000000000')\n\n# if your batch is still running\nresponse.processed\n=> 1\nresponse.total\n=> 2\nresponse.message\n=> 'Your batch is being processed.'\n\n# if your batch is complete\nresponse.emails\n=> [{'email': 'evan@emailable.com', 'state': 'deliverable'...}, {'email': 'support@emailable.com', 'state': 'deliverable'...}...]\n\n# get the counts\nresponse.total_counts\n=>{'deliverable': 2, 'undeliverable': 0 ...}\nresponse.reason_counts\n=>{'accepted_email': 2, 'rejected_email': 0 ...}\n```\n\n## Development\n\nTests can be run with the following command:\n\n```shell\npytest\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/emailable/emailable-python.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This is the official python wrapper for the Emailable API.",
"version": "3.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/emailable/emailable-python/issues",
"Documentation": "https://emailable.com/docs/api?python",
"Homepage": "https://github.com/emailable/emailable-python",
"Source Code": "https://github.com/emailable/emailable-python"
},
"split_keywords": [
"emailable",
"email",
"verification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93dccaac6a9eb8fb3b74d5323a55a550cdf09f5ce0638f306f5d4d462c96c2b7",
"md5": "6c2a4fc121ff2b7bfd85cc2dc4ede4aa",
"sha256": "298bb496aa73a9030810483dae3b41803bb494e2af7547329cdb2a67f403f479"
},
"downloads": -1,
"filename": "emailable-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c2a4fc121ff2b7bfd85cc2dc4ede4aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6091,
"upload_time": "2024-09-20T17:34:02",
"upload_time_iso_8601": "2024-09-20T17:34:02.403833Z",
"url": "https://files.pythonhosted.org/packages/93/dc/caac6a9eb8fb3b74d5323a55a550cdf09f5ce0638f306f5d4d462c96c2b7/emailable-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "534245f5a7ca51261c2189bb4ebe48c6c081b040b40dd92a72fec90f3dc4c912",
"md5": "88c096fd648d44ef440e868e07d1248f",
"sha256": "3a79e0b593cf69decebb5f3443b84b48d2ca96071547b93d9278c62d4b1c4605"
},
"downloads": -1,
"filename": "emailable-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "88c096fd648d44ef440e868e07d1248f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5251,
"upload_time": "2024-09-20T17:34:03",
"upload_time_iso_8601": "2024-09-20T17:34:03.233144Z",
"url": "https://files.pythonhosted.org/packages/53/42/45f5a7ca51261c2189bb4ebe48c6c081b040b40dd92a72fec90f3dc4c912/emailable-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-20 17:34:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "emailable",
"github_project": "emailable-python",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "emailable"
}
JSON
