Categorygithub.com/zerobounce/zerobouncego
modulepackage
1.1.0
Repository: https://github.com/zerobounce/zerobouncego.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
17
Dependents
0
Files
1.5k SLOC

# README

Go ZeroBounce API

Go implementation for ZeroBounce Email Validation API v2.

Link to the original repo

Installation and Usage

go get github.com/zerobounce/zerobouncego

This package uses the zero-bounce API which requires an API key. This key can be provide in three ways:

  1. through an environment variable ZERO_BOUNCE_API_KEY (loaded automatically in code)
  2. through an .env file that contains ZERO_BOUNCE_API_KEY and then calling following method before usage:
zerobouncego.ImportApiKeyFromEnvFile()
  1. by settings explicitly in code, using the following method:
zerobouncego.SetApiKey("mysecretapikey")

Generic API methods

package main

import (
	"fmt"
	"time"

	"github.com/zerobounce/zerobouncego"
)

func main() {
	zerobouncego.SetApiKey("... Your API KEY ...")

	// Check your account's credits
	credits, error_ := zerobouncego.GetCredits()
	if error_ != nil {
		fmt.Println("Error from credits: ", error_.Error())
	} else {
		fmt.Println("Credits left:", credits.Credits())
	}

	// Check your account's usage of the API
	start_time := time.Date(2023, 1, 1, 0, 0, 0, 0, time.Local)
	end_time := time.Now()
	usage, error_ := zerobouncego.GetApiUsage(start_time, end_time)
	if error_ != nil {
		fmt.Println("Error from API usage: ", error_.Error())
	} else {
		fmt.Println("Total API calls: ", usage.Total)
	}
}

Validation

1. Single email validation

package main

import (
    "fmt"
    "os"
    "github.com/zerobounce/zerobouncego"
)

func main() {

    zerobouncego.APIKey = "... Your API KEY ..."

	// For Querying a single E-Mail and IP
	// IP can also be an empty string
	response, error_ := zerobouncego.Validate("[email protected]", "123.123.123.123")

	if error_ != nil {
		fmt.Println("error occurred: ", error_.Error())
	} else {
		// Now you can check status
		if response.Status == zerobouncego.S_INVALID {
			fmt.Println("This email is valid")
		}

		// .. or Sub-status
		if response.SubStatus == zerobouncego.SS_POSSIBLE_TYPO {
			fmt.Println("This email might have a typo")
		}
	}
}

2. Batch validation

package main

import (
	"fmt"

	"github.com/zerobounce/zerobouncego"
)

func main() {
	zerobouncego.SetApiKey("... Your API KEY ...")

	emails_to_validate := []zerobouncego.EmailToValidate{
		{EmailAddress: "[email protected]", IPAddress: "99.110.204.1"},
		{EmailAddress: "[email protected]", IPAddress: "1.1.1.1"},
		{EmailAddress: "[email protected]"},
		{EmailAddress: "[email protected]"},
	}

	response, error_ := zerobouncego.ValidateBatch(emails_to_validate)
	if error_ != nil {
		fmt.Println("error ocurred while batch validating: ", error_.Error())
	} else {
		fmt.Printf("%d successful result fetched and %d error results\n", len(response.EmailBatch), len(response.Errors))
		if len(response.EmailBatch) > 0 {
			fmt.Printf(
				"email '%s' has status '%s' and sub-status '%s'\n",
				response.EmailBatch[0].Address,
				response.EmailBatch[0].Status,
				response.EmailBatch[0].SubStatus,
			)
		}
	}
}

3. Bulk file validation

package main

import (
	"fmt"
	"os"
	"time"

	"github.com/zerobounce/zerobouncego"
)


func main() {
	zerobouncego.SetApiKey("... Your API KEY ...")
	import_file_path := "PATH_TO_CSV_TO_IMPORT"
	result_file_path := "PATH_TO_CSV_TO_EXPORT"

	file, error_ := os.Open(import_file_path)
	if error_ != nil {
		fmt.Println("error while opening the file: ", error_.Error())
		return
	}

	defer file.Close()
	csv_file := zerobouncego.CsvFile{
		File: file, HasHeaderRow: false, EmailAddressColumn: 1, FileName: "emails.csv",
	}
	submit_response, error_ := zerobouncego.BulkValidationSubmit(csv_file, false)
	if error_ != nil {
		fmt.Println("error while submitting data: ", error_.Error())
		return
	}

	fmt.Println("submitted file ID: ", submit_response.FileId)
	var file_status *zerobouncego.FileStatusResponse
	file_status, _ = zerobouncego.BulkValidationFileStatus(submit_response.FileId)
	fmt.Println("file status: ", file_status.FileStatus)
	fmt.Println("completion percentage: ", file_status.Percentage(), "%")

	// wait for the file to get completed
	fmt.Println()
	fmt.Println("Waiting for the file to get completed ")
	var seconds_waited int = 1
	for file_status.Percentage() != 100. {
		time.Sleep(time.Duration(seconds_waited) * time.Second)
		if seconds_waited < 10 {
			seconds_waited += 1
		}

		file_status, error_ = zerobouncego.BulkValidationFileStatus(submit_response.FileId)
		if error_ != nil {
			fmt.Print()
			fmt.Print("error ocurred while polling for status: ", error_.Error())
			return
		}
		fmt.Printf("..%.2f%% ", file_status.Percentage())
	}
	fmt.Println()
	fmt.Println("File validation complete")

	// save validation result
	result_file, error_ := os.OpenFile(result_file_path, os.O_RDWR | os.O_CREATE, 0644)
	if error_ != nil {
		fmt.Println("error on creating result file: ", error_.Error())
		return
	}
	error_ = zerobouncego.BulkValidationResult(submit_response.FileId, result_file)
	defer result_file.Close()
	if error_ != nil {
		fmt.Println("error on fetch validation result: ", error_.Error())
		return
	}
	fmt.Printf("Saved validation result at path: %s\n", result_file_path)

	// delete result file, after saving
	delete_status, error_ := zerobouncego.BulkValidationFileDelete(file_status.FileId)
	if error_ != nil {
		fmt.Println("error on fetch file delete: ", error_.Error())
		return
	}
	fmt.Println(delete_status)
}

Example import file:

[email protected]
[email protected]
[email protected]
[email protected]

Example export file:

"Email Address","ZB Status","ZB Sub Status","ZB Account","ZB Domain","ZB First Name","ZB Last Name","ZB Gender","ZB Free Email","ZB MX Found","ZB MX Record","ZB SMTP Provider","ZB Did You Mean"
"[email protected]","do_not_mail","disposable","","","zero","bounce","male","False","true","mx.example.com","example",""
"[email protected]","invalid","mailbox_not_found","","","zero","bounce","male","False","true","mx.example.com","example",""
"[email protected]","valid","","","","zero","bounce","male","False","true","mx.example.com","example",""
"[email protected]","do_not_mail","toxic","","","zero","bounce","male","False","true","mx.example.com","example",""
"[email protected]","invalid","mailbox_not_found","","","zero","bounce","male","False","true","mx.example.com","example",""
"[email protected]","invalid","failed_syntax_check","","","zero","bounce","male","False","true","mx.example.com","example",""

4. AI scoring

package main

import (
	"fmt"
	"os"
	"time"

	"github.com/zerobounce/zerobouncego"
)


func main() {
	zerobouncego.SetApiKey("... Your API KEY ...")
	zerobouncego.ImportApiKeyFromEnvFile()
	import_file_path := "./emails.csv"
	result_file_path := "./validation_result.csv"

	file, error_ := os.Open(import_file_path)
	if error_ != nil {
		fmt.Println("error while opening the file: ", error_.Error())
		return
	}

	defer file.Close()
	csv_file := zerobouncego.CsvFile{
		File: file, HasHeaderRow: false, EmailAddressColumn: 1, FileName: "emails.csv",
	}
	submit_response, error_ := zerobouncego.AiScoringFileSubmit(csv_file, false)
	if error_ != nil {
		fmt.Println("error while submitting data: ", error_.Error())
		return
	}

	fmt.Println("submitted file ID: ", submit_response.FileId)
	var file_status *zerobouncego.FileStatusResponse
	file_status, _ = zerobouncego.AiScoringFileStatus(submit_response.FileId)
	fmt.Println("file status: ", file_status.FileStatus)
	fmt.Println("completion percentage: ", file_status.Percentage(), "%")

	// wait for the file to get completed
	fmt.Println()
	fmt.Println("Waiting for the file to get completed ")
	var seconds_waited int = 1
	for file_status.Percentage() != 100. {
		time.Sleep(time.Duration(seconds_waited) * time.Second)
		if seconds_waited < 10 {
			seconds_waited += 1
		}

		file_status, error_ = zerobouncego.AiScoringFileStatus(submit_response.FileId)
		if error_ != nil {
			fmt.Print()
			fmt.Print("error ocurred while polling for status: ", error_.Error())
			return
		}
		fmt.Printf("..%.2f%% ", file_status.Percentage())
	}
	fmt.Println()
	fmt.Println("File validation complete")

	// save validation result
	result_file, error_ := os.OpenFile(result_file_path, os.O_RDWR | os.O_CREATE, 0644)
	if error_ != nil {
		fmt.Println("error on creating result file: ", error_.Error())
		return
	}
	error_ = zerobouncego.AiScoringResult(submit_response.FileId, result_file)
	defer result_file.Close()
	if error_ != nil {
		fmt.Println("error on fetch validation result: ", error_.Error())
		return
	}
	fmt.Printf("Saved validation result at path: %s\n", result_file_path)

	// delete result file, after saving
	delete_status, error_ := zerobouncego.AiScoringFileDelete(file_status.FileId)
	if error_ != nil {
		fmt.Println("error on fetch file delete: ", error_.Error())
		return
	}
	fmt.Println(delete_status)
}

Example import file:

[email protected]
[email protected]
[email protected]
[email protected]

Example export file:

"Email Address","ZeroBounceQualityScore"
"[email protected]","0"
"[email protected]","10"
"[email protected]","10"
"[email protected]","2"

Email Finder

Email Finder allows you to search for new business email addresses using our proprietary technologies

1. Single Email finder

package main

import (
	"fmt"

	"github.com/zerobounce/zerobouncego"
)

func main() {
	zerobouncego.SetApiKey("... Your API KEY ...")

	response, error_ := zerobouncego.FindEmail("example.com", "John", "", "Doe")
	if error_ != nil {
		fmt.Println(error_.Error())
		return
	}
	fmt.Println(response)
}

2. Single domain finder

package main

import (
	"fmt"

	"github.com/zerobounce/zerobouncego"
)

func main() {
	zerobouncego.SetApiKey("... Your API KEY ...")
	response, error_ := zerobouncego.DomainSearch("example.com")
	if error_ != nil {
		fmt.Println(error_.Error())
		return
	}
	fmt.Println(response)
}

Testing

This package contains both unit tests and integration tests (which are excluded from the test suite). Unit test files are the ones ending in "_test.go" (as go requires) and the integration tests are ending in ("_integration_t.go").

In order to run the integration tests:

  • set appropriate ZERO_BOUNCE_API_KEY environment variable
  • rename all "_integration_t.go" into "_integration_test.go"
  • run either individual or all tests (go test .)

NOTE: currently, the unit tests can be updated such that, by removing the mocking and explicit API key setting, they should work as integration tests as well AS LONG AS a valid API key is provided via environment

# Functions

AiScoringFileDelete - delete the result file associated with a file ID.
BulkValidationFileStatus - check the percentage of completion of a file uploaded for AI scoring.
AiScoringSubmit - submit a file with emails for AI scoring.
AiScoringResult - save a csv containing the results of the file previously sent, that corresponds to the given file ID parameter.
BulkValidationFileDelete - delete the result file associated with a file ID.
BulkValidationFileStatus - check the percentage of completion of a file uploaded for bulk validation.
BulkValidationResult - save a csv containing the results of the file with the given file ID.
BulkValidationSubmit - submit a file with emails for validation.
DoGetRequest does a GET request to the API.
DomainSearch - attempts to detect possible patterns a specific company uses.
No description provided by the author
ErrorFromResponse given a response who is expected to have a json structure, generate a joined response of all values within that json This function was done because error messages have inconsistent keys eg: error, message, Message etc.
FindEmail uses parameters to provide valid business email.
GenericFileDelete - delete the result file associated with a file ID.
GenericFileStatusCheck - check the percentage of completion of a file uploaded for the operation represented by the given endpoint.
GenericFileSubmit - submits a csv file to an operation represented by the given endpoint.
GenericResultFetch - save a csv containing the results of the file with the given file ID.
GetActivityData check the activity of an email address.
GetApiUsage the usage of the API within a date interval.
GetCredits gets credits balance.
ImportApiKeyFromEnvFile provided that a .env file can be found where the program is running, load it, extract the API key and set it.
ImportCsvFile - import a file to be uploaded for validation.
PrepareURL prepares the URL for a get request by attaching both the API key and the given params.
SetApiKey set the API key explicitly.
No description provided by the author
TestInvalidApiKey test expecting one error, relevant to invalid API key.
No description provided by the author
Validate validates a single email.
ValidateBatch given a list of emails (and, optionally, their IPs), validate them and return both validation details and errors about the emails sent.

# Constants

No description provided by the author
CONTENT_TYPE_JSON
No description provided by the author
CONTENT_TYPE_OCTET_STREAM
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Content-type: application/octet-stream.
No description provided by the author
No description provided by the author
No description provided by the author
Content-type: application/octet-stream.
No description provided by the author
No description provided by the author
No description provided by the author
validation statuses.
validation statuses.
validation statuses.
validation statuses.
validation statuses.
validation statuses.
validation statuses.
No description provided by the author
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
validation sub statuses.
No description provided by the author

# Variables

API_KEY the API key used in order to make the requests.
No description provided by the author

# Structs

No description provided by the author
ApiUsageResponse response structure for the API usage functionality.
CreditsResponse response of the credits balance.
CsvFile - used for bulk validations and AI scoring.
DomainFormats part of the `FindEmailResponse` describing other domain formats.
EmailBatchError an error unit received in the response, that can be associated with an email sent to the batch validate endpoint.
EmailToValidate represents one unit send to the batch validate endpoint.
BulkValidationFileStatus - response payload after a file status check.
FileValidationResponse - response payload from a successful.
FindEmailResponse response structure for Find Email API `Confidence` field possible values: low, medium, high, unknown, undetermined (it is inconsistent as it can be either lowercase or uppercase).
TESTING.
ValidateBatchResponse represents the structure of a 200OK batch validate response.
ValidateResponse response structure for single email validation.

# Interfaces

APIResponse basis for api responses.