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_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 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)