Quickstart guide

![alt text](https://www.emailage.com/wp-content/uploads/2018/01/logo- dark.svg)(https://www.emailage.com)

The Python-language Emailage API client helps companies integrate with our highly efficient fraud risk and scoring system. By calling our API endpoints and simply passing us an email and/or IP Address, companies will be provided with real-time risk scoring assessments based around machine learning and proprietary algorithms that evolve with new fraud trends.

Quickstart guide

Requirements

Python 2.7+ or 3.3+

Installation

The Emailage client can be installed with pip:

$ pip install emailage-official

or directly from the source code:

$ git clone https://github.com/emailage/Emailage_Python.git
$ cd Emailage_Python
$ python setup.py install

Typical usage

Instantiate a client

Targeting the production servers

from emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token')

Targeting the sandbox environment

from emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)

Query risk score information for the provided email address, IP address,

or a combination

from emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)
# For an email address
client.query('[email protected]')
# For an IP address
client.query('127.0.0.1')
# For a combination. Please note the order
client.query(('[email protected]', '127.0.0.1'))
# Pass a User Defined Record ID (URID).
# Can be used when you want to add an identifier for a query.
# The identifier will be displayed in the result.
client.query('[email protected]', urid='My record ID for [email protected]')

Explicit methods produce the same request while validating format of the arguments passed

from emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)
# For an email address
client.query_email('[email protected]')
# For an IP address
client.query_ip_address('127.0.0.1')
# For a combination. Please note the order
client.query_email_and_ip_address('[email protected]', '127.0.0.1')
# Pass a User Defined Record ID
client.query_email_and_ip_address('[email protected]', '127.0.0.1', urid='My record ID for [email protected] and 127.0.0.1')

Mark an email address as fraud, good, or neutral

You may report that you have found that an email address is good, is associated with fraud, or is neither (neutral).

The call to flag an email address as fraud must be accompanied by one of the fraud reasons enumerated below:

Card Not Present Fraud
Customer Dispute (Chargeback)
First Party Fraud
First Payment Default
Identify Theft (Fraud Application)
Identify Theft (Account Take Over)
Suspected Fraud (Not Confirmed)
Synthetic ID
Other

Mark an email address as fraud because of Synthetic ID

from emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)
client.flag('fraud', '[email protected]', 8)
client.flag_as_fraud('[email protected]', 8)
# Mark an email address as good
client.flag('good', '[email protected]')
client.flag_as_good('[email protected]')
# Unflag an email address that was previously marked as good or fraud
client.flag('neutral', '[email protected]')
client.remove_flag('[email protected]')

Exceptions

This client can throw exceptions on any of the following issues:

When Requests has an issue, like not being able to connect from your server to the Emailage API,
When incorrectly-formatted JSON is received,
When an incorrectly-formatted email or IP address is passed to a flagging or explicit querying method.

Client API reference

module `emailage.client`

class `emailage.client.EmailageClient`( secret , token ,

sandbox=False , _tls_version= <SSLMethod.PROTOCOL_TLSv1_2: 5>, timeout=None , http_method='GET' )

Primary proxy to the Emailage API for end-users of the package

Creates an instance of the EmailageClient using the specified credentials and environment

Parameters

secret ( str ) Consumer secret, e.g. SID or API key.
token ( str ) Consumer token.
sandbox ( bool ) (Optional) Whether to use a sandbox instead of a production server. Uses production by default
tls_version (see TlsVersions) (Optional) Uses TLS version 1.2 by default (TlsVersions.TLSv1_2 | TlsVersions.TLSv1_1)
timeout ( float ) (Optional) The timeout to be used for sent requests
http_method (see HttpMethods) (Optional) The HTTP method (GET or POST) to be used for sending requests

Example

>>> from emailage.client import EmailageClient
>>> from emailage import protocols
>>> client = EmailageClient('consumer_secret', 'consumer_token', sandbox=True, tls_version=protocols.TLSv1_1)
>>> fraud_report = client.query(('[email protected]', '192.168.1.1'), urid='some_unique_identifier')

Example

>>> from emailage.client import EmailageClient
>>> from emailage import protocols
>>> client = EmailageClient('consumer_secret', 
...                         'consumer_token', sandbox=True, timeout=300)
>>> fraud_report = client.query(('[email protected]', '192.168.1.1'), urid='some_unique_identifier')

flag( flag , query , fraud_code=None )

Base method used to flag an email address as fraud, good, or neutral

Parameters

flag ( str ) type of flag you wish to associate with the identifier ( fraud | good | neutral )
query ( str ) Email to be flagged
fraud_code ( int ) (Optional) Required if flag is fraud, one of the IDs in emailage.client.EmailageClient.FRAUD_CODES

Returns

JSON dict of the confirmation response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag('good', '[email protected]')
>>> response_json = client.flag('fraud', '[email protected]', fraud_code=6)
>>> response_json = client.flag('neutral', '[email protected]')

flag_as_fraud( query , fraud_code )

Mark an email address as fraud.

Parameters

query ( str ) Email to be flagged
fraud_code ( int ) Reason for the email to be marked as fraud; must be one of the IDs in emailage.client.EmailageClient.FRAUD_CODES

Returns

JSON dict of the confirmation response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag_as_fraud('[email protected]', 8)

flag_as_good( query )

Mark an email address as good.

Parameters

query ( str ) Email to be flagged

Returns

JSON dict of the confirmation response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag_as_good('[email protected]')

query( query , **params )

Base query method providing support for email, IP address, and optional additional parameters

Parameters

query ( str | ( str , str ) ) RFC2822-compliant Email, RFC791-compliant IP, or both
params ( kwargs ) keyword-argument form for parameters such as urid, first_name, last_name, etc.

Returns

JSON dict of the response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> response_json = client.query('[email protected]')
>>> # Email address only
>>> response_json = client.query('[email protected]')
>>> # IP Address only
>>> response_json = client.query('209.85.220.41')
>>> # For a combination. Please note the order
>>> response_json = client.query(('[email protected]', '209.85.220.41'))
>>> # Pass a User Defined Record ID (URID) as an optional parameter
>>> response_json = client.query('[email protected]', urid='My record ID for [email protected]')

query_email( email , **params )

Query a risk score information for the provided email address.

Parameters

email ( str ) RFC2822-compliant Email
params ( kwargs ) (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.

Returns

JSON dict of the response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email('[email protected]')

query_email_and_ip_address( email , ip , **params )

Query a risk score information for the provided combination of an Email and IP address

Parameters

email ( str ) RFC2822-compliant Email
ip ( str ) RFC791-compliant IP
params ( kwargs ) (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.

Returns

JSON dict of the response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email_and_ip_address('[email protected]', '209.85.220.41')

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email_and_ip_address('[email protected]', '209.85.220.41',
...     urid='My record ID for [email protected] and 209.85.220.41')

query_ip_address( ip , **params )

Query a risk score information for the provided IP address.

Parameters

ip ( str ) RFC791-compliant IP
params ( kwargs ) (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.

Returns

JSON dict of the response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_ip_address('209.85.220.41')

remove_flag( query )

Unflag an email address that was marked as good or fraud previously.

Parameters

query ( str ) Email to be flagged

Returns

JSON dict of the confirmation response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.remove_flag('[email protected]')

request( endpoint , **params )

Base method to generate requests for the Emailage validator and flagging APIs

Parameters

endpoint ( str ) API endpoint to send the request ( | /flag )
params ( kwargs ) keyword-argument list of parameters to send with the request

Returns

JSON dict of the response generated by the API

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> response = client.request('/flag', email='[email protected]', flag='good')
>>> response['query']['email']
u'user20180830001%40domain20180830001.com'

set_api_domain( domain , _tls_version= <SSLMethod.PROTOCOL_TLSv1_2: 5>)

Explicitly set the API domain to use for a session of the client, typically used in testing scenarios

Parameters

domain (str see :class: ApiDomains) API domain to use for the session
tls_version (see :class: TlsVersions) (Optional) Uses TLS version 1.2 by default (TlsVersions.TLSv1_2 | TlsVersions.TLSv1_1)

Returns

None

Example

>>> from emailage.client import EmailageClient
>>> from emailage.client import ApiDomains
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> client.set_api_domain(ApiDomains.sandbox)
>>> client.domain
'https://sandbox.emailage.com'

Example

>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> client.set_api_domain('https://testing.emailage.com')
>>> client.domain
'https://testing.emailage.com'

set_credentials( secret , token )

Explicitly set the authentication credentials to be used when generating a request in the current session. Useful when you want to change credentials after initial creation of the client.

Parameters

secret Consumer secret, e.g. SID or API key
token Consumer token

Returns

None

set_http_method( http_method )

Explicitly set the Http method (GET or POST) through which you will be sending the request. This method will be used for any future calls made with this instance of the client until another method is specified

Parameters

http_method (str see :class: HttpMethods) HttpMethod to use for sending requests

Returns

None

Example

>>> from emailage.client import EmailageClient, HttpMethods
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> client.set_http_method(HttpMethods.POST)
>>> client.http_method
'POST'

class `emailage.client.ApiDomains`

API URLs for the specified domains

class `emailage.client.HttpMethods`

HttpMethod constants to pass to the client

class `emailage.client.TlsVersions`

An enumeration of the TLS versions supported by the Emailage API

module `emailage.signature`

`emailage.signature.create`( method , url , params , hmac_key )

Generates the OAuth1.0 signature used as the value for the query string parameter oauth_signature

Parameters

method ( str ) HTTP method that will be used to send the request ( GET | POST )
url ( str ) API domain and endpoint up to the ?
params ( dict ) user-provided query string parameters and the OAuth1.0 parameters :method add_oauth_entries_to_fields_dict:
hmac_key ( str ) for Emailage users, this is your consumer token with an & (ampersand) appended to the end

Returns

str value used for oauth_signature

Example

>>> from emailage.signature import add_oauth_entries_to_fields_dict, create
>>> your_api_key = 'SOME_KEY'
>>> your_hmac_key = 'SOME_SECRET' + '&'
>>> api_url = 'https://sandbox.emailage.com/emailagevalidator/'
>>> query_params = { 'query': '[email protected]', 'user_email': '[email protected]' }
>>> query_params = add_oauth_entries_to_fields_dict(your_api_key, query_params)
>>> query_params['oauth_signature'] = create('GET', api_url, query_params, your_hmac_key)

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
docs		docs
emailage		emailage
.coveragerc		.coveragerc
.gitattributes		.gitattributes
.gitignore		.gitignore
.pep257		.pep257
.pep8rc		.pep8rc
.pylintrc		.pylintrc
.scrutinizer.yml		.scrutinizer.yml
.travis.yml		.travis.yml
CHANGES.md		CHANGES.md
CONTRIBUTING.md		CONTRIBUTING.md
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
license.md		license.md
mkdocs.yml		mkdocs.yml
requirements.txt		requirements.txt
scent.py		scent.py
setup.py		setup.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Quickstart guide

Requirements

Installation

Typical usage

Instantiate a client

Targeting the production servers

Targeting the sandbox environment

Query risk score information for the provided email address, IP address,

Mark an email address as fraud, good, or neutral

Mark an email address as fraud because of Synthetic ID

Exceptions

Client API reference

module `emailage.client`

class `emailage.client.EmailageClient`( secret , token ,

class `emailage.client.ApiDomains`

class `emailage.client.HttpMethods`

class `emailage.client.TlsVersions`

module `emailage.signature`

`emailage.signature.create`( method , url , params , hmac_key )

About

Releases

Packages

Contributors 6

Languages

License

emailage/Emailage_Python

Folders and files

Latest commit

History

Repository files navigation

Quickstart guide

Requirements

Installation

Typical usage

Instantiate a client

Targeting the production servers

Targeting the sandbox environment

Query risk score information for the provided email address, IP address,

Mark an email address as fraud, good, or neutral

Mark an email address as fraud because of Synthetic ID

Exceptions

Client API reference

module emailage.client

class emailage.client.EmailageClient( secret , token ,

class emailage.client.ApiDomains

class emailage.client.HttpMethods

class emailage.client.TlsVersions

module emailage.signature

emailage.signature.create( method , url , params , hmac_key )

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 6

Languages

module `emailage.client`

class `emailage.client.EmailageClient`( secret , token ,

class `emailage.client.ApiDomains`

class `emailage.client.HttpMethods`

class `emailage.client.TlsVersions`

module `emailage.signature`

`emailage.signature.create`( method , url , params , hmac_key )

Packages