def query(self, query, **params):
""" Base query method providing support for email, IP address, and optional additional parameters
:param query: RFC2822-compliant Email, RFC791-compliant IP, or both
:param params: keyword-argument form for parameters such as urid, first_name, last_name, etc.
:return: JSON dict of the response generated by the API
:type query: str | (str, str)
:type params: kwargs
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> response_json = client.query('*****@*****.**')
>>> # Email address only
>>> response_json = client.query('*****@*****.**')
>>> # IP Address only
>>> response_json = client.query('209.85.220.41')
>>> # For a combination. Please note the order
>>> response_json = client.query(('*****@*****.**', '209.85.220.41'))
>>> # Pass a User Defined Record ID (URID) as an optional parameter
>>> response_json = client.query('*****@*****.**', urid='My record ID for [email protected]')
"""
if type(query) is tuple:
validation.assert_email(query[0])
validation.assert_ip(query[1])
query = '+'.join(query)
params['query'] = query
return self.request('', **params)
def query(self, query, **params):
""" Base query method providing support for email, IP address, and optional additional parameters
:param query: RFC2822-compliant Email, RFC791-compliant IP, or both
:param params: keyword-argument form for parameters such as urid, first_name, last_name, etc.
:return: JSON dict of the response generated by the API
:type query: str | (str, str)
:type params: kwargs
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('consumer_secret', 'consumer_token')
>>> response_json = client.query('*****@*****.**')
>>> # Email address only
>>> response_json = client.query('*****@*****.**')
>>> # IP Address only
>>> response_json = client.query('209.85.220.41')
>>> # For a combination. Please note the order
>>> response_json = client.query(('*****@*****.**', '209.85.220.41'))
>>> # Pass a User Defined Record ID (URID) as an optional parameter
>>> response_json = client.query('*****@*****.**', urid='My record ID for [email protected]')
"""
if type(query) is tuple:
validation.assert_email(query[0])
validation.assert_ip(query[1])
query = '+'.join(query)
params['query'] = query
return self.request('', **params)
def test_validates_email(self):
validation.assert_email(self.correct_email)
self.assertRaises(ValueError, validation.assert_email,
self.incorrect_email)
self.assertRaises(ValueError, validation.assert_email, self.correct_ip)
self.assertRaises(ValueError, validation.assert_email,
self.incorrect_ip)
def flag(self, flag, query, fraud_code=None):
"""Mark an email address as fraud, good, or neutral.
Args:
flag (str): Either fraud, neutral, or good.
query (str): Email to be flagged.
fraud_code (int): Reason why the email is considered fraud. ID of the one of FRAUD_CODES options.
Required only if you flag something as fraud.
See emailage.Client.FRAUD_CODES for the list of available reasons and their IDs.
"""
flags = ['fraud', 'neutral', 'good']
if flag not in flags:
raise ValueError("flag must be one of {}. {} is given.".format(', '.join(flags), flag))
validation.assert_email(query)
params = dict(flag=flag, query=query)
if flag == 'fraud':
codes = self.FRAUD_CODES
if type(fraud_code) is not int:
raise ValueError("fraud_code must be an integer from 1 to {} corresponding to {}. {} is given.".format(len(codes), ', '.join(codes.values()), fraud_code))
if fraud_code not in range(1, len(codes) + 1):
fraud_code = 9
params['fraudcodeID'] = fraud_code
return self.request('/flag', **params)
def flag(self, flag, query, fraud_code=None):
"""Mark an email address as fraud, good, or neutral.
Args:
flag (str): Either fraud, neutral, or good.
query (str): Email to be flagged.
fraud_code (int): Reason why the email is considered fraud. ID of the one of FRAUD_CODES options.
Required only if you flag something as fraud.
.. seealso:: `emailage.client.EmailageClient.FRAUD_CODES` for the list of available reasons and their IDs.
"""
flags = ['fraud', 'neutral', 'good']
if flag not in flags:
raise ValueError(validation.Messages.FLAG_NOT_ALLOWED_FORMAT.format(', '.join(flags), flag))
validation.assert_email(query)
params = dict(flag=flag, query=query)
if flag == 'fraud':
codes = self.FRAUD_CODES
if type(fraud_code) is not int:
raise ValueError(
validation.Messages.FRAUD_CODE_RANGE_FORMAT.format(
len(codes), ', '.join(codes.values()), fraud_code)
)
if fraud_code not in range(1, len(codes) + 1):
fraud_code = 9
params['fraudcodeID'] = fraud_code
return self.request('/flag', **params)
def query_email_and_ip_address(self, email, ip, **params):
"""Query a risk score information for the provided combination of an Email and IP address
:param email: RFC2822-compliant Email
:param ip: RFC791-compliant IP
:param params: (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.
:return: JSON dict of the response generated by the API
:type email: str
:type ip: str
:type params: kwargs
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email_and_ip_address('*****@*****.**', '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('*****@*****.**', '209.85.220.41',
... urid='My record ID for [email protected] and 209.85.220.41')
"""
validation.assert_email(email)
validation.assert_ip(ip)
return self.query((email, ip), **params)
def flag(self, flag, query, fraud_code=None):
"""Mark an email address as fraud, good, or neutral.
Args:
flag (str): Either fraud, neutral, or good.
query (str): Email to be flagged.
fraud_code (int): Reason why the email is considered fraud. ID of the one of FRAUD_CODES options.
Required only if you flag something as fraud.
See emailage.Client.FRAUD_CODES for the list of available reasons and their IDs.
"""
flags = ['fraud', 'neutral', 'good']
if flag not in flags:
raise ValueError("flag must be one of {}. {} is given.".format(
', '.join(flags), flag))
validation.assert_email(query)
params = dict(flag=flag, query=query)
if flag == 'fraud':
codes = self.FRAUD_CODES
if type(fraud_code) is not int:
raise ValueError(
"fraud_code must be an integer from 1 to {} corresponding to {}. {} is given."
.format(len(codes), ', '.join(codes.values()), fraud_code))
if fraud_code not in range(1, len(codes) + 1):
fraud_code = 9
params['fraudcodeID'] = fraud_code
return self.request('/flag', **params)
def query_email(self, email, **params):
"""Query a risk score information for the provided email address.
This method differs from #query in that it ensures that the string supplied is in rfc2822 format.
Args:
email (str)
**params: keywords arguments for #query
"""
validation.assert_email(email)
return self.query(email, **params)
def query_email(self, email, **params):
"""Query a risk score information for the provided email address.
This method differs from #query in that it ensures that the string supplied is in rfc2822 format.
Args:
email (str)
**params: keywords arguments for #query
"""
validation.assert_email(email)
return self.query(email, **params)
def query_email_and_ip_address(self, email, ip, **params):
"""Query a risk score information for the provided combination of an Email and IP address.
This method differs from #query in that it ensures that the strings supplied are in rfc2822 and rfc791 formats.
Args:
email (str)
ip (str)
**params: keywords arguments for #query
"""
validation.assert_email(email)
validation.assert_ip(ip)
return self.query((email, ip), **params)
def query_email_and_ip_address(self, email, ip, **params):
"""Query a risk score information for the provided combination of an Email and IP address.
This method differs from #query in that it ensures that the strings supplied are in rfc2822 and rfc791 formats.
Args:
email (str)
ip (str)
**params: keywords arguments for #query
"""
validation.assert_email(email)
validation.assert_ip(ip)
return self.query((email, ip), **params)
def flag(self, flag, query, fraud_code=None):
""" Base method used to flag an email address as fraud, good, or neutral
:param flag: type of flag you wish to associate with the identifier ( 'fraud' | 'good' | 'neutral' )
:param query: Email to be flagged
:param fraud_code:
(Optional) Required if flag is 'fraud', one of the IDs in `emailage.client.EmailageClient.FRAUD_CODES`
:return: JSON dict of the confirmation response generated by the API
:type flag: str
:type query: str
:type fraud_code: int
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag('good', '*****@*****.**')
>>> response_json = client.flag('fraud', '*****@*****.**', fraud_code=6)
>>> response_json = client.flag('neutral', '*****@*****.**')
"""
flags = ['fraud', 'neutral', 'good']
if flag not in flags:
raise ValueError(
validation.Messages.FLAG_NOT_ALLOWED_FORMAT.format(
', '.join(flags), flag))
validation.assert_email(query)
params = dict(flag=flag, query=query)
if flag == 'fraud':
codes = self.FRAUD_CODES
if type(fraud_code) is not int:
raise ValueError(
validation.Messages.FRAUD_CODE_RANGE_FORMAT.format(
len(codes), ', '.join(codes.values()), fraud_code))
if fraud_code not in range(1, len(codes) + 1):
fraud_code = 9
params['fraudcodeID'] = fraud_code
return self.request('/flag', **params)
def query_email(self, email, **params):
"""Query a risk score information for the provided email address.
:param email: RFC2822-compliant Email
:param params: (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.
:return: JSON dict of the response generated by the API
:type email: str
:type params: kwargs
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email('*****@*****.**')
"""
validation.assert_email(email)
return self.query(email, **params)
def query_email(self, email, **params):
"""Query a risk score information for the provided email address.
:param email: RFC2822-compliant Email
:param params: (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.
:return: JSON dict of the response generated by the API
:type email: str
:type params: kwargs
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email('*****@*****.**')
"""
validation.assert_email(email)
return self.query(email, **params)
def flag(self, flag, query, fraud_code=None):
""" Base method used to flag an email address as fraud, good, or neutral
:param flag: type of flag you wish to associate with the identifier ( 'fraud' | 'good' | 'neutral' )
:param query: Email to be flagged
:param fraud_code:
(Optional) Required if flag is 'fraud', one of the IDs in `emailage.client.EmailageClient.FRAUD_CODES`
:return: JSON dict of the confirmation response generated by the API
:type flag: str
:type query: str
:type fraud_code: int
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.flag('good', '*****@*****.**')
>>> response_json = client.flag('fraud', '*****@*****.**', fraud_code=6)
>>> response_json = client.flag('neutral', '*****@*****.**')
"""
flags = ['fraud', 'neutral', 'good']
if flag not in flags:
raise ValueError(validation.Messages.FLAG_NOT_ALLOWED_FORMAT.format(', '.join(flags), flag))
validation.assert_email(query)
params = dict(flag=flag, query=query)
if flag == 'fraud':
codes = self.FRAUD_CODES
if type(fraud_code) is not int:
raise ValueError(
validation.Messages.FRAUD_CODE_RANGE_FORMAT.format(
len(codes), ', '.join(codes.values()), fraud_code)
)
if fraud_code not in range(1, len(codes) + 1):
fraud_code = 9
params['fraudcodeID'] = fraud_code
return self.request('/flag', **params)
def query_email_and_ip_address(self, email, ip, **params):
"""Query a risk score information for the provided combination of an Email and IP address
:param email: RFC2822-compliant Email
:param ip: RFC791-compliant IP
:param params: (Optional) keyword-argument form for parameters such as urid, first_name, last_name, etc.
:return: JSON dict of the response generated by the API
:type email: str
:type ip: str
:type params: kwargs
:Example:
>>> from emailage.client import EmailageClient
>>> client = EmailageClient('My account SID', 'My auth token', sandbox=True)
>>> response_json = client.query_email_and_ip_address('*****@*****.**', '209.85.220.41')
>>> response_json = client.query_email_and_ip_address('*****@*****.**', '209.85.220.41', urid='My record ID for [email protected] and 209.85.220.41')
"""
validation.assert_email(email)
validation.assert_ip(ip)
return self.query((email, ip), **params)
def test_validates_email(self):
validation.assert_email(self.correct_email)
self.assertRaises(ValueError, validation.assert_email, self.incorrect_email)
self.assertRaises(ValueError, validation.assert_email, self.correct_ip)
self.assertRaises(ValueError, validation.assert_email, self.incorrect_ip)
