NAV Navbar
shell ruby
  • Authentication
  • Emails
  • Account
  • Rate Limits
  • Errors
  • Authentication

    Introduction

    curl "https://api.blazeverify/v1/{api_endpoint}?api_key={your_api_key}"
    
    BlazeVerify.api_key = 'your_api_key'
    

    Make sure to replace your_api_key with your API key.

    Blaze Verify uses API keys to allow access to our API. To get started, sign up for an account here.

    Blaze Verify expects the API key to be included in all API requests to the server as a URL parameter, or as POST data for POST endpoints.

    Your account will have two API keys. One will be your test key, denoted by a test_ prefix. A live key will have a live_ prefix. Test keys can be used to send requests to the /verify and /batch endpoints.

    Security

    Blaze Verify has two types of API Keys. Please use the proper API key for your application.

    Public API Keys

    This type of key is meant to be used anywhere that the key will be exposed publicly. One example would be using the API in the Javascript of a website to verify that user entered email addresses are valid.

    To prevent abuse of your account, we require that you set up a list of trusted domains when you create a public API key. All requests that are made using a public API key will only work if they originate from a trusted domain. They will also be rate limited to 10 requests per day per user.

    Also note that only the /verify endpoint can be used with public API keys.

    Private API Keys

    This type of key is meant to be used on the server-side of your application. These keys should never be exposed because they are not protected.

    Should a private API key be compromised, you should immediately generate a new one by using the "roll key" function in the dashboard.

    Emails

    Verify an email

    curl "https://api.blazeverify.com/v1/verify?email=john@smith.com&api_key=your_api_key"
    
    BlazeVerify.verify('john@smith.com')
    

    The above command returns JSON structured like this:

    {
      "accept_all": null,
      "did_you_mean": null,
      "disposable": false,
      "domain": "gmail.com",
      "email": "john.smith@gmail.com",
      "first_name": "John",
      "free": true,
      "full_name": "John Smith",
      "gender": "male",
      "last_name": "Smith",
      "mx_record": "aspmx.l.google.com",
      "reason": "accepted_email",
      "role": false,
      "score": 100,
      "smtp_provider": "google",
      "state": "deliverable",
      "tag": null,
      "user": "john.smith"
    }
    

    If a verification is taking too long, a 249 status code will be returned:

    {
      "message": "Your request is taking longer than normal. Please send your request again."
    }
    

    Verify a single email. If a verification request takes longer than the timeout, you may retry this request for up to 5 minutes. After 5 minutes, further requests will count against your usage. The verification result will be returned when it is available.

    When a test key is used, a random sample response will be returned.

    HTTP Request

    GET https://api.blazeverify.com/v1/verify

    Parameters

    Parameter Required Description
    email true The email you want verified.
    smtp false The SMTP step takes up a majority of the API's response time. If you would like to speed up your response times, you can disable this step. Default: true
    accept_all false Does an accept-all check. Heavily impacts API's response time. Default: false
    timeout false Optional timeout to wait for response (in seconds). Min: 2, Max: 30. Default: 5
    api_key true Your API key.

    Verify a batch of emails

    curl -X POST "https://api.blazeverify.com/v1/batch" -d "emails=tim@smith.com,john@smith.com" -d "url=http://example.com/callback" -d "api_key=your_api_key"
    
    emails = ['tim@smith.com', 'john@smith.com']
    callback = 'http://example.com/callback'
    batch = BlazeVerify::Batch.new(emails, callback: callback)
    batch.verify
    

    The above command returns JSON structured like this:

    {
      "message": "Batch successfully created.",
      "id": "5cf6dd30093f96d2ac34bb0a"
    }
    

    Verify a batch of emails. The emails should be sent as a parameter "emails" and should be separated by commas. Up to 1,000 emails can be sent per batch.

    If a URL was specified, the results will be sent via HTTP POST upon completion.

    When a test key is used, a successful batch creation response will be returned along with an example batch id.

    HTTP Request

    POST https://api.blazeverify.com/v1/batch

    Parameters

    Parameter Required Description
    emails true A comma separated list of emails.
    url false A URL that will receive the batch results via HTTP POST.
    api_key true Your API key.

    Get the status of a batch

    curl "https://api.blazeverify.com/v1/batch?api_key=your_api_key&batch_id=5cf6dd30093f96d2ac34bb0a"
    
    batch = BlazeVerify::Batch.new('5cf6dd30093f96d2ac34bb0a')
    batch.status
    

    If your batch is incomplete, a message will be returned, as well as the batch's progress if it is processing:

    {
      "message": "Your batch is being processed.",
      "processed": 1,
      "total": 2
    }
    

    When the batch completes, the results will be returned, too:

    {
      "emails": [
        {
          "accept_all": false,
          "did_you_mean": null,
          "disposable": false,
          "domain": "gmail.com",
          "email": "john.smith@gmail.com",
          "first_name": "John",
          "free": true,
          "full_name": "John Smith",
          "gender": "male",
          "last_name": "Smith",
          "mx_record": "aspmx.l.google.com",
          "reason": "accepted_email",
          "role": false,
          "score": 95,
          "smtp_provider": "google",
          "state": "deliverable",
          "tag": null,
          "user": "john.smith"
        },
        {
          "accept_all": false,
          "did_you_mean": null,
          "disposable": false,
          "domain": "smith.com",
          "email": "tim@smith.com",
          "first_name": "Tim",
          "free": false,
          "full_name": "Tim",
          "gender": "male",
          "last_name": null,
          "mx_record": "mx1.smith.com",
          "reason": "accepted_email",
          "role": false,
          "score": 100,
          "smtp_provider": null,
          "state": "deliverable",
          "tag": null,
          "user": "tim"
        }
      ],
      "id": "5cf6dd30093f96d2ac34bb0a",
      "message": "Batch verification completed.",
      "reason_counts": {
        "accepted_email": 2,
        "invalid_domain": 0,
        "invalid_email": 0,
        "invalid_smtp": 0,
        "low_deliverability": 0,
        "low_quality": 0,
        "no_connect": 0,
        "rejected_email": 0,
        "timeout": 0,
        "unavailable_smtp": 0,
        "unexpected_error": 0
      },
      "total_counts": {
        "deliverable": 2,
        "processed": 2,
        "risky": 0,
        "total": 2,
        "undeliverable": 0,
        "unknown": 0
      }
    }
    

    GET requests to the batch endpoint will get the current status of the batch verification job specified in the "id" parameter.

    When a credit card transaction is necessary to obtain enough credits to verify a batch, billing related messages will be returned if there is an error. These will be sent with a 402 response code.

    When a test key is used, a random sample response will be returned.

    HTTP Request

    GET https://api.blazeverify.com/v1/batch

    Parameters

    Parameter Required Description
    api_key true Your API key.
    id true The id of the batch.

    Account

    Get account info

    curl "https://api.blazeverify.com/v1/account?api_key=your_api_key"
    
    BlazeVerify.account
    

    The above command returns JSON structured like this:

    {
      "owner_email": "john@smith.com",
      "available_credits": 1337
    }
    

    Get general account information like the email of the account owner and available credits.

    HTTP Request

    GET https://api.blazeverify.com/v1/account

    Parameters

    Parameter Required Description
    api_key true Your API key.

    Rate Limits

    {
      "message": "Rate Limit Exceeded"
    }
    

    When rate limits are exceeded, the 429 status code will be returned.

    There are different rate limits for different API endpoints. These rate limits are shown below.

    Endpoint Method Rate Limit
    /v1/account 3 per second
    /v1/batch POST 2 per second
    /v1/batch GET 5 per second
    /v1/verify 5 per second

    Errors

    {
      "message": "API key is required"
    }
    

    The Blazeverify API uses the following error codes:

    Code Error Meaning
    400 Bad Request Your request is structured incorrectly.
    401 Unauthorized You did not send an API key.
    402 Payment Required You don't have enough credits to complete this request.
    403 Forbidden Your API key is invalid.
    404 Not Found The specified resource does not exist.
    429 Too Many Requests You're requesting an endpoint too often.
    500 Internal Server Error A server error occurred. Please try again later, or contact support if you're having trouble.
    503 Service Unavailable We're temporarily offline for maintenance. Please try again later.