ZeroBounce iOS SDK

This SDK contains methods for interacting easily with ZeroBounce API. More information about ZeroBounce you can find in the official documentation.

Installation (CocoaPods)

Add the pod to your Podfile pod 'ZeroBounceSDK' and run pod install

USAGE

Import the SDK in your file:

import ZeroBounceSDK

Initialize the SDK with your api key and preferred api:

ZeroBounceSDK.shared.initialize(apiKey: "<YOUR_API_KEY>", apiBaseUrl: .API_DEFAULT_URL)

Examples

Then you can use any of the SDK methods, for example:

• Validate an email address

let email = "<EMAIL_ADDRESS>"   // The email address you want to validate
let ipAddress = "127.0.0.1"     // The IP Address the email signed up from (Optional)

ZeroBounceSDK.shared.validate(email: email, ipAddress: ipAddress) { result in
    switch result {
    case .Success(let response):
        NSLog("validate success response=\(response)")
    case .Failure(let error):
        NSLog("validate failure error=\(String(describing: error))")
        switch error as? ZBError {
        case ZBError.notInitialized:
            break
        case ZBError.decodeError(let messages):
            /// decodeError is used to extract and decode errors and messages 
            /// when they are not part of the response object
            break
        default:
            break
        }
    }
}

• Validate up to 100 email addresses using Batch Email Validator

// The email addresses you want to validate
let emails = [ 
    ["email_address": "<EMAIL_ADDRESS_1>"], 
    ["email_address": "<EMAIL_ADDRESS_2>", "ip_address": "127.0.0.1"]
] 

ZeroBounceSDK.shared.validateBatch(emails: emails) { result in
    switch result {
    case .Success(let response):
        NSLog("validate success response=\(response)")
    case .Failure(let error):
        NSLog("validate failure error=\(String(describing: error))")
    }
}

• Find the email based on a given domain name or company name

let domain = "<DOMAIN_NAME>" // The domain name for which to find the email format
let companyName = "<COMPANY_NAME>" // The company name for which to find the email format
let firstName = "<FIRST_NAME>" // The first name whose email format is being searched
let middleName = "<MIDDLE_NAME>" // The middle name whose email format is being searched (Optional)
let lastName = "<LAST_NAME>" // The last name whose email format is being searched (Optional)

ZeroBounceSDK.shared.findEmail(
    domain: domain,
    firstName: firstName,
    middleName: middleName,
    lastName: lastName
) { result in
    switch result {
    case .Success(let response):
        NSLog("guessFormat success response=\(response)")
    case .Failure(let error):
        NSLog("guessFormat failure error=\(String(describing: error))")
    }
}

ZeroBounceSDK.shared.findEmail(
    companyName: companyName,
    firstName: firstName,
    middleName: middleName,
    lastName: lastName
) { result in
    switch result {
    case .Success(let response):
        NSLog("guessFormat success response=\(response)")
    case .Failure(let error):
        NSLog("guessFormat failure error=\(String(describing: error))")
    }
}

• Find the domain based on a given domain name or company name

let domain = "<DOMAIN_NAME>" // The domain name for which to find the email format
let companyName = "<COMPANY_NAME>" // The company name for which to find the email format

ZeroBounceSDK.shared.findEmail(
    domain: domain
) { result in
    switch result {
    case .Success(let response):
        NSLog("guessFormat success response=\(response)")
    case .Failure(let error):
        NSLog("guessFormat failure error=\(String(describing: error))")
    }
}

ZeroBounceSDK.shared.findEmail(
    companyName: companyName
) { result in
    switch result {
    case .Success(let response):
        NSLog("guessFormat success response=\(response)")
    case .Failure(let error):
        NSLog("guessFormat failure error=\(String(describing: error))")
    }
}

• Check how many credits you have left on your account

ZeroBounceSDK.shared.getCredits() { result in
    switch result {
    case .Success(let response):
        NSLog("getCredits success response=\(response)")
        let credits = response.credits
    case .Failure(let error):
        NSLog("getCredits failure error=\(String(describing: error))")
    }
}

• Check if your email inbox has been active in the past 30, 60, 90, 180, 365, 730 or 1095 days

let email = "<EMAIL_ADDRESS>"   // The email address you want to check

ZeroBounceSDK.shared.getActivityData(email: email) { result in
    switch result {
    case .Success(let response):
        NSLog("getActivityData success response=\(response)")
    case .Failure(let error):
        NSLog("getActivityData failure error=\(String(describing: error))")
    }
}

• Check your API usage for a given period of time

let startDate = Date();    // The start date of when you want to view API usage
let endDate = Date();      // The end date of when you want to view API usage

ZeroBounceSDK.shared.getApiUsage(startDate: startDate, endDate: endDate) { result in
    switch result {
    case .Success(let response):
        NSLog("getApiUsage success response=\(response)")
    case .Failure(let error):
        NSLog("getApiUsage failure error=\(String(describing: error))")
    }
}

• The sendfile API allows user to send a file for bulk email validation

let filePath = File("<FILE_PATH>"); // The csv or txt file
let emailAddressColumn = 3;         // The index of "email" column in the file. Index starts at 1
let firstNameColumn = 3;            // The index of "first name" column in the file
let lastNameColumn = 3;             // The index of "last name" column in the file
let genderColumn = 3;               // The index of "gender" column in the file
let ipAddressColumn = 3;            // The index of "IP address" column in the file
let hasHeaderRow = true;            // If this is `true` the first row is considered as table headers
let returnUrl = "https://domain.com/called/after/processing/request";

ZeroBounceSDK.shared.sendFile(
    filePath: filePath,
    emailAddressColumn: emailAddressColumn,
    returnUrl: returnUrl,
    firstNameColumn: firstNameColumn,
    lastNameColumn: lastNameColumn,
    genderColumn: genderColumn,
    ipAddressColumn: ipAddressColumn,
    hasHeaderRow: hasHeaderRow
) { result in
    switch result {
    case .Success(let response):
        NSLog("sendFile success response=\(response)")
    case .Failure(let error):
        NSLog("sendFile failure error=\(String(describing: error))")
    }
}

• The getfile API allows users to get the validation results file for the file been submitted using sendfile API

let fileId = "<FILE_ID>";    // The returned file ID when calling sendfile API

ZeroBounceSDK.shared.getfile(fileId: fileId) { result in
    switch result {
    case .Success(let response):
        NSLog("getfile success response=\(response)")
    case .Failure(let error):
        NSLog("getfile failure error=\(String(describing: error))")
    }
}

• Check the status of a file uploaded via "sendFile" method

let fileId = "<FILE_ID>";    // The returned file ID when calling sendfile API

ZeroBounceSDK.shared.fileStatus(fileId: fileId) { result in
    switch result {
    case .Success(let response):
        NSLog("fileStatus success response=\(response)")
    case .Failure(let error):
        NSLog("fileStatus failure error=\(String(describing: error))")
    }
}

• Deletes the file that was submitted using scoring sendfile API. File can be deleted only when its status is Complete

let fileId = "<FILE_ID>";    // The returned file ID when calling sendfile API

ZeroBounceSDK.shared.deleteFile(fileId: fileId) { result in
    switch result {
    case .Success(let response):
        NSLog("deleteFile success response=\(response)")
    case .Failure(let error):
        NSLog("deleteFile failure error=\(String(describing: error))")
    }
}

AI Scoring API

• The scoringSendFile API allows user to send a file for bulk email validation

let filePath = File("<FILE_PATH>"); // The csv or txt file
let emailAddressColumn = 3;         // The index of "email" column in the file. Index starts at 1
let hasHeaderRow = true;            // If this is `true` the first row is considered as table headers
let returnUrl = "https://domain.com/called/after/processing/request";

ZeroBounceSDK.shared.scoringSendFile(
    filePath: filePath,
    emailAddressColumn: emailAddressColumn,
    returnUrl: returnUrl,
    hasHeaderRow: hasHeaderRow
) { result in
    switch result {
    case .Success(let response):
        NSLog("sendFile success response=\(response)")
    case .Failure(let error):
        NSLog("sendFile failure error=\(String(describing: error))")
    }
}

• The scoringGetFile API allows users to get the validation results file for the file been submitted using scoringSendFile API

let fileId = "<FILE_ID>";    // The returned file ID when calling scoringSendFile API

ZeroBounceSDK.shared.scoringGetfile(fileId: fileId) { result in
    switch result {
    case .Success(let response):
        NSLog("getfile success response=\(response)")
    case .Failure(let error):
        NSLog("getfile failure error=\(String(describing: error))")
    }
}

• Check the status of a file uploaded via "scoringSendFile" method

let fileId = "<FILE_ID>";    // The returned file ID when calling scoringSendFile API

ZeroBounceSDK.shared.scoringFileStatus(fileId: fileId) { result in
    switch result {
    case .Success(let response):
        NSLog("fileStatus success response=\(response)")
    case .Failure(let error):
        NSLog("fileStatus failure error=\(String(describing: error))")
    }
}

• Deletes the file that was submitted using scoring scoringSendFile API. File can be deleted only when its status is Complete

let fileId = "<FILE_ID>";    // The returned file ID when calling scoringSendFile API

ZeroBounceSDK.shared.scoringDeleteFile(fileId: fileId) { result in
    switch result {
    case .Success(let response):
        NSLog("deleteFile success response=\(response)")
    case .Failure(let error):
        NSLog("deleteFile failure error=\(String(describing: error))")
    }
}

Sample App

• You can also clone the repo and access the Sample App inside the project to check out some examples. Just initialize the SDK with your own API key and uncomment the endpoint that you want to test.

Running Unit Tests

Unit tests are located in Zero Bounce iOS SDKTests/Zero_Bounce_iOS_SDKTests.swift and use XCTest with the Mocker library for HTTP mocking.

Option 1: Xcode (Recommended)

1. Open Zero Bounce iOS SDK.xcworkspace in Xcode
2. Select the Zero Bounce iOS SDK scheme
3. Press ⌘U (or Product → Test)

Option 2: Command Line (macOS)

Prerequisites: macOS with Xcode and CocoaPods installed.

cd zero-bounce-ios-sdk

# Install dependencies
pod install

# Run tests using Mac Catalyst (no iOS Simulator required)
xcodebuild test \
  -workspace "Zero Bounce iOS SDK.xcworkspace" \
  -scheme "Zero Bounce iOS SDK" \
  -destination 'platform=macOS,variant=Mac Catalyst' \
  CODE_SIGN_IDENTITY="-" \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGNING_ALLOWED=NO \
  ENABLE_USER_SCRIPT_SANDBOXING=NO

With iOS Simulator (requires iOS Simulator runtime installed via Xcode → Settings → Platforms):

xcodebuild test \
  -workspace "Zero Bounce iOS SDK.xcworkspace" \
  -scheme "Zero Bounce iOS SDK" \
  -destination 'platform=iOS Simulator,name=iPhone 16'

Expected Output

All 22 unit tests should pass:

Test Suite 'All tests' passed.
   Executed 22 tests, with 0 failures (0 unexpected) in 0.370 seconds

Any of the following email addresses can be used for testing the API, no credits are charged for these test email addresses:

• disposable@example.com
• invalid@example.com
• valid@example.com
• toxic@example.com
• donotmail@example.com
• spamtrap@example.com
• abuse@example.com
• unknown@example.com
• catch_all@example.com
• antispam_system@example.com
• does_not_accept_mail@example.com
• exception_occurred@example.com
• failed_smtp_connection@example.com
• failed_syntax_check@example.com
• forcible_disconnect@example.com
• global_suppression@example.com
• greylisted@example.com
• leading_period_removed@example.com
• mail_server_did_not_respond@example.com
• mail_server_temporary_error@example.com
• mailbox_quota_exceeded@example.com
• mailbox_not_found@example.com
• no_dns_entries@example.com
• possible_trap@example.com
• possible_typo@example.com
• role_based@example.com
• timeout_exceeded@example.com
• unroutable_ip_address@example.com
• free_email@example.com

Publish

See the sdk-docs (CocoaPods) guide in the SDKs repo for pod trunk push and release steps.