Package: emailage-official
![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 guideRequirementsPython 2.7+ or 3.3+InstallationThe Emailage client can be installed with pip:$ pip install emailage-officialor directly from the source code:$ git clone https://github.com/emailage/Emailage_Python.git
$ cd Emailage_Python
$ python setup.py installTypical usageInstantiate a clientTargeting the production serversfrom emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token')Targeting the sandbox environmentfrom 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 combinationfrom emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)
# For an email address
client.query('test@example.com')
# For an IP address
client.query('127.0.0.1')
# For a combination. Please note the order
client.query(('test@example.com', '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('test@example.com', urid='My record ID for test@example.com')Explicit methods produce the same request while validating format of the
arguments passedfrom emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)
# For an email address
client.query_email('test@example.com')
# 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('test@example.com', '127.0.0.1')
# Pass a User Defined Record ID
client.query_email_and_ip_address('test@example.com', '127.0.0.1', urid='My record ID for test@example.com and 127.0.0.1')Mark an email address as fraud, good, or neutralYou 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 fraudmustbe accompanied by one of the
fraud reasons enumerated below:Card Not Present FraudCustomer Dispute (Chargeback)First Party FraudFirst Payment DefaultIdentify Theft (Fraud Application)Identify Theft (Account Take Over)Suspected Fraud (Not Confirmed)Synthetic IDOtherMark an email address as fraud because of Synthetic IDfrom emailage.client import EmailageClient
client = EmailageClient('My account SID', 'My auth token', sandbox=True)
client.flag('fraud', 'test@example.com', 8)
client.flag_as_fraud('test@example.com', 8)
# Mark an email address as good
client.flag('good', 'test@example.com')
client.flag_as_good('test@example.com')
# Unflag an email address that was previously marked as good or fraud
client.flag('neutral', 'test@example.com')
client.remove_flag('test@example.com')ExceptionsThis 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 referencemoduleemailage.clientclassemailage.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 packageCreates an instance of the EmailageClient using the specified credentials and
environmentParameterssecret(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 defaulttls_version(seeTlsVersions)  (Optional) Uses TLS version 1.2 by default (TlsVersions.TLSv1_2 | TlsVersions.TLSv1_1)timeout(float)  (Optional) The timeout to be used for sent requestshttp_method(seeHttpMethods)  (Optional) The HTTP method (GET or POST) to be used for sending requestsExample>>> 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(('useremail@example.co.uk', '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(('useremail@example.co.uk', '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 neutralParametersflag(str)  type of flag you wish to associate with the identifier ( fraud | good | neutral )query(str)  Email to be flaggedfraud_code(int)  (Optional) Required if flag is fraud, one of the IDs in emailage.client.EmailageClient.FRAUD_CODESReturnsJSON dict of the confirmation response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag('good', 'test@example.com')
>>> response_json = client.flag('fraud', 'test@example.com', fraud_code=6)
>>> response_json = client.flag('neutral', 'test@example.com')flag_as_fraud(query,fraud_code)Mark an email address as fraud.Parametersquery(str)  Email to be flaggedfraud_code(int)  Reason for the email to be marked as fraud; must be one of the IDs in emailage.client.EmailageClient.FRAUD_CODESReturnsJSON dict of the confirmation response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag_as_fraud('test@example.com', 8)flag_as_good(query)Mark an email address as good.Parametersquery(str)  Email to be flaggedReturnsJSON dict of the confirmation response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag_as_good('test@example.com')query(query,**params)Base query method providing support for email, IP address, and optional
additional parametersParametersquery(str |(str,str))  RFC2822-compliant Email, RFC791-compliant IP, or bothparams(kwargs)  keyword-argument form for parameters such as urid, first_name, last_name, etc.ReturnsJSON dict of the response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> response_json = client.query('test@example.com')
>>> # Email address only
>>> response_json = client.query('test@example.com')
>>> # IP Address only
>>> response_json = client.query('209.85.220.41')
>>> # For a combination. Please note the order
>>> response_json = client.query(('test@example.com', '209.85.220.41'))
>>> # Pass a User Defined Record ID (URID) as an optional parameter
>>> response_json = client.query('test@example.com', urid='My record ID for test@example.com')query_email(email,**params)Query a risk score information for the provided email address.Parametersemail(str)  RFC2822-compliant Emailparams(kwargs)  (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.ReturnsJSON dict of the response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email('test@example.com')query_email_and_ip_address(email,ip,**params)Query a risk score information for the provided combination of an Email and IP
addressParametersemail(str)  RFC2822-compliant Emailip(str)  RFC791-compliant IPparams(kwargs)  (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.ReturnsJSON dict of the response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email_and_ip_address('test@example.com', '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('test@example.com', '209.85.220.41',
...     urid='My record ID for test@example.com and 209.85.220.41')query_ip_address(ip,**params)Query a risk score information for the provided IP address.Parametersip(str)  RFC791-compliant IPparams(kwargs)  (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.ReturnsJSON dict of the response generated by the APIExample>>> 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.Parametersquery(str)  Email to be flaggedReturnsJSON dict of the confirmation response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.remove_flag('test@example.com')request(endpoint,**params)Base method to generate requests for the Emailage validator and flagging APIsParametersendpoint(str)  API endpoint to send the request (  | /flag )params(kwargs)  keyword-argument list of parameters to send with the requestReturnsJSON dict of the response generated by the APIExample>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> response = client.request('/flag', email='user20180830001@domain20180830001.com', 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 scenariosParametersdomain(str see :class: ApiDomains)  API domain to use for the sessiontls_version(see :class: TlsVersions)  (Optional) Uses TLS version 1.2 by default (TlsVersions.TLSv1_2 | TlsVersions.TLSv1_1)ReturnsNoneExample>>> 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.ParameterssecretConsumer secret, e.g. SID or API keytokenConsumer tokenReturnsNoneset_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 specifiedParametershttp_method(str see :class: HttpMethods)  HttpMethod to use for sending
requestsReturnsNoneExample>>> from emailage.client import EmailageClient, HttpMethods
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> client.set_http_method(HttpMethods.POST)
>>> client.http_method
'POST'classemailage.client.ApiDomainsAPI URLs for the specified domainsclassemailage.client.HttpMethodsHttpMethod constants to pass to the clientclassemailage.client.TlsVersionsAn enumeration of the TLS versions supported by the Emailage APImoduleemailage.signatureemailage.signature.create(method,url,params,hmac_key)Generates the OAuth1.0 signature used as the value for the query string
parameter oauth_signatureParametersmethod(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 endReturnsstr value used for oauth_signatureExample>>> 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': 'user.you.are.validating@gmail.com', 'user_email': 'admin@yourcompany.com' }
>>> 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)(C)2018, Emailage Dev Team. | Powered by Sphinx 2.2.0 & Alabaster 0.7.12 |
Page sourceRevision History1.2.2 (11 March 2020)Fix POST requests for Python 2.7 users1.2.1 (3 March 2020)Remove mock dependency from requirements.txt1.2.0 (10 January 2020)HTTP verb for requests is a parameter to__init__, defaults to GETRequest timeout can be specified as parameter to__init__UTF-8 characters may be sent via the POST request1.1.6 (14 December 2018)Fix choice of URL encoding function for Python 2.7 users1.1.4 (17 September 2018)Corrected IPv4 validation Regex to allow 0s in octets 2,3,41.1.0 (30 August 2018)Corrected bug in the URL encoding of spacesSignificantly expanded documentation of signature functionsExtracted all OAuth signature generation logic from request generation into the signature moduleExplicit decoding of API response bytes removes the need to run a Regex over the response1.0.2 (30 October 2017)Corrected the validation of IPv4 and IPv6 IP addressesAdded an optional parameter to specify TLS 1.1 or 1.2 on the initialization of EmailageClient