Email Verification

Verify a single email address or in bulk with MailerSend's Email Verification API. Create and fetch lists and retrieve your results.

This endpoint allows you to verify emails through the MailerSend Email API.

Verify an email

If you want to verify a single email, use this POST request:

POST https://api.mailersend.com/v1/email-verification/verify

Request parameters

JSON parameter	Type	Required	Limitations	Details
`email`	`string`	yes	Max: `320`, valid email address

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->verifyEmail('test@example.com');

More examples

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.verifyEmail("test@example.com")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = EmailVerificationBuilder().email("test@example.com").build_verify_email()

response = ms.email_verification.verify_email(request)

More examples

package main

import (
	"context"
	"os"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(os.Getenv("MAILERSEND_API_KEY"))

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	options := &mailersend.SingleEmailVerificationOptions{
		Email: "john@doe.com",
	}

	_, _, err := ms.EmailVerification.VerifySingle(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.SingleEmailVerificationResponse;

public void verifyEmail() {

    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");

    try {

        SingleEmailVerificationResponse response = ms.emailVerification().verifyEmail("test@example.com");

        System.out.println(response.status);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email_verification = Mailersend::EmailVerification.new(ms_client)
ms_email_verification.verify_an_email(email: 'test@example.com')

More examples

Responses

Valid

{
  "status": "valid"
}

Not enough credits error

Response Code: 402 Payment Required
Response Headers:
	content-type: application/json

{
  "message": "Not enough credits. Credits required: 1"
}

Verification results

The possible outcome of an email validation can be grouped in 3 categories: Valid, Risky and Do Not Send.

Valid

Result	Description
`valid`	Email is safe to send.

Risky

Result	Description
`catch_all`	Recipient's mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person.
`mailbox_full`	Recipient’s inbox is full and may not be able to receive new emails.
`role_based`	Email is role-based and may not be associated with a single, specific person but a group of people.
`unknown`	We are unable to determine if the email is valid or not valid.
`failed`	We could not perform the check due to timeouts. Verify the email by importing a list.

Do Not Send

Result	Description
`syntax_error`	The email address is not valid.
`typo`	The email address has a typo. Correct the email address and retest.
`mailbox_not_found`	Recipient’s inbox does not exist.
`disposable`	The email address is a temporary inbox and should be removed from your lists.
`mailbox_blocked`	The email address’ mailbox is blocked by its service provider due to poor sending practices.

See - Validation errors

Verify an email (Async)

Check a single email and receive the result asynchronously to avoid delays and timeouts, use this POST request:

POST https://api.mailersend.com/v1/email-verification/verify-async

Request parameters

JSON parameter	Type	Required	Limitations	Details
`email`	`string`	yes	Max: `320`, valid email address

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->verifyAsync('test@example.com');

More examples

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.verifyEmailAsync("test@example.com")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = EmailVerificationBuilder().email("test@example.com").build_verify_email_async()

response = ms.email_verification.verify_email_async(request)

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.AsyncEmailVerificationResponse;

public void verifyEmailAsync() {

    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");

    try {

        AsyncEmailVerificationResponse response = ms.emailVerification().verifyEmailAsync("test@example.com");

        System.out.println(response.id);
        System.out.println(response.status);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examples

Responses

Valid

Response Code: 201 CREATED
Response Headers:
	content-type: application/json

{
  "data": {
    "id": "67c83bf24a5d02568029ee10",
    "address": "test@email.com",
    "status": "queued",
    "result": null,
    "error": null
  }
}

Not enough credits error

Response Code: 402 Payment Required
Response Headers:
	content-type: application/json

{
  "message": "Not enough credits. Credits required: 1"
}

See - Validation errors

Get async email verification status

If you want to retrieve information about an async email verification status, use this GET request or Receive via webhook:

GET https://api.mailersend.com/v1/email-verification/verify-async/{email_verification_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`email_verification_id`	`string`	yes

Check verification status

You can use this endpoint to check the verification status, with the following possible status:

Status	Description
`queued`	The verification process is ongoing.
`completed`	The verification process has finished successfully.
`failed`	The verification process has run into an internal error.

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->getVerifyAsyncResult('email_verification_id');

More examples

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.getVerifyEmailAsyncStatus("email_verification_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = EmailVerificationBuilder().email_verification_id("email_verification_id").build_async_status()

response = ms.email_verification.get_async_status(request)

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.AsyncEmailVerificationResponse;

public void getVerifyEmailAsyncStatus() {

    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");

    try {

        AsyncEmailVerificationResponse response = ms.emailVerification().getVerifyEmailAsyncStatus("async verification id");

        System.out.println(response.status);
        System.out.println(response.result);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examples

Responses

Valid

{
  "data": {
    "id": "67c8863ce2fbd4fc8a7611cc",
    "address": "test@email.com",
    "status": "completed",
    "result": "unknown",
    "error": null
  }
}

Response fields

Field	Type	Details
`data.id`	`string`	The unique identifier of the async verification.
`data.address`	`string`	The email address that was verified.
`data.status`	`string`	The current verification status (`queued`, `completed`, or `failed`).
`data.result`	`string\|null`	The verification result once completed. `null` while still processing.
`data.error`	`string\|null`	Error message when `status` is `failed`, if one is available. `null` otherwise.

Get all lists

Get all email verifications lists with this GET request:

GET https://api.mailersend.com/v1/email-verification

Request parameters

Query parameter	Type	Required	Limitations	Details
`page`	`int`	no	Min: `1`
`limit`	`int`	no	Min: `10`, Max: `100`	Default: `25`

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->getAll($page = 1, $limit = 10);

More examples

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.list({
  limit: 10,
  page: 1
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = EmailVerificationBuilder().build_lists()

response = ms.email_verification.list_verifications(request)

More examples

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	options := &mailersend.ListEmailVerificationOptions{
		Page:  1,
		Limit: 25,
	}

	_, _, err := ms.EmailVerification.List(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.EmailVerificationList;
import com.mailersend.sdk.emailverification.EmailVerificationLists;

public void getLists() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        EmailVerificationLists lists = ms.emailVerification().getLists();
            
        for (EmailVerificationList list : lists.lists) {
            System.out.println(list.id);
            System.out.println(list.name);
        }
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email_verification = Mailersend::EmailVerification.new(ms_client)
ms_email_verification.list(page: 1, limit: 10)

More examples

Responses

Valid

{
  "data": [
    {
      "id": "n3k6d1jr1eq50x4v",
      "name": "Example List",
      "total": 0,
      "verification_started": null,
      "verification_ended": null,
      "created_at": "2022-07-19T15:11:18.000000Z",
      "updated_at": "2022-07-19T15:11:18.000000Z",
      "status": {
        "name": "uploading",
        "count": 0
      },
      "source": "api",
      "statistics": {
        "valid": 0,
        "catch_all": 0,
        "mailbox_full": 0,
        "role_based": 0,
        "unknown": 0,
        "syntax_error": 0,
        "typo": 0,
        "mailbox_not_found": 0,
        "disposable": 0,
        "mailbox_blocked": 0,
        "failed": 0,
        "not_verified": 0
      }
    }
  ],
  "links": {
    "first": "http:\/\/localhost:8080\/api\/v1\/email-verification?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "current_page_url": "http:\/\/localhost:8080\/api\/v1\/email-verification?page=1",
    "from": 1,
    "path": "http:\/\/localhost:8080\/api\/v1\/email-verification",
    "per_page": 25,
    "to": 1
  }
}

Get a single list

If you want to retrieve information about a single email verification list, use this GET request:

GET https://api.mailersend.com/v1/email-verification/{email_verification_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`email_verification_id`	`string`	yes

Query parameter	Type	Required	Limitations	Details
`detailed`	`boolean`	no		When true, response includes an `emails` object with paginated email results.
`page`	`integer`	no	Min: `1`	Only relevant when `detailed=true`.
`limit`	`integer`	no	Min: `1`, Max: `100`	Only relevant when `detailed=true`.

Check verification status

You can use this endpoint to check the verification status, with the following possible status:

Status	Description
`uploading`	The email addresses are being uploaded to our system.
`created`	The list has been created and is ready to be verified.
`verifying`	The verification process is ongoing.
`verified`	The verification process has finished successfully.
`failed`	The verification process has run into an internal error.
`canceled`	The verification process was canceled.
`paused`	The verification process is paused.

You can also check how many emails have been verified by consulting the count property of the status object.

Example of status in the payload:

"status": {
  "name": "verifying",
  "count": 5
}

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->find('email_verification_id');

$mailersend->emailVerification->find(
    'email_verification_id',
    $detailed = true,
    $page = 1,
    $limit = 10,
);

More examples

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.single("email_verification_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = EmailVerificationBuilder().email_verification_id("list-id").build_get()

response = ms.email_verification.get_verification(request)

More examples

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	_, _, err := ms.EmailVerification.Get(ctx, "email-verification-id")
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.EmailVerificationList;

public void getList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        EmailVerificationList list = ms.emailVerification().getList("list id");

        System.out.println(list.name);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email_verification = Mailersend::EmailVerification.new(ms_client)
ms_email_verification.get_single_list(email_verification_id: 'your-email-verification-id')

More examples

Responses

Valid

{
  "data": {
    "id": "n3k6d1jr1eq50x4v",
    "name": "Example List",
    "total": 0,
    "verification_started": null,
    "verification_ended": null,
    "created_at": "2022-07-19T15:11:18.000000Z",
    "updated_at": "2022-07-19T15:11:18.000000Z",
    "status": {
      "name": "uploading",
      "count": 0
    },
    "source": "api",
    "statistics": {
      "valid": 0,
      "catch_all": 0,
      "mailbox_full": 0,
      "role_based": 0,
      "unknown": 0,
      "syntax_error": 0,
      "typo": 0,
      "mailbox_not_found": 0,
      "disposable": 0,
      "mailbox_blocked": 0,
      "failed": 0,
      "not_verified": 0
    }
  }
}

Valid with detailed=true

{
  "data": {
    "id": "n3k6d1jr1eq50x4v",
    "name": "Example List",
    "total": 2,
    "verification_started": "2022-07-19T15:24:19.000000Z",
    "verification_ended": "2022-07-19T15:30:00.000000Z",
    "created_at": "2022-07-19T15:11:18.000000Z",
    "updated_at": "2022-07-19T15:30:00.000000Z",
    "status": {
      "name": "verified",
      "count": 2
    },
    "source": "api",
    "statistics": {
      "valid": 1,
      "catch_all": 0,
      "mailbox_full": 0,
      "role_based": 0,
      "unknown": 0,
      "syntax_error": 0,
      "typo": 1,
      "mailbox_not_found": 0,
      "disposable": 0,
      "mailbox_blocked": 0,
      "failed": 0,
      "not_verified": 0
    },
    "emails": {
      "data": [
        {
          "address": "example1@mail.com",
          "result": "typo"
        },
        {
          "address": "example2@gmail.com",
          "result": "valid"
        }
      ],
      "pagination": {
        "current_page": 1,
        "per_page": 25,
        "total": 2,
        "last_page": 1,
        "from": 1,
        "to": 2
      },
      "links": {
        "first": "https://api.mailersend.com/v1/email-verification/n3k6d1jr1eq50x4v?detailed=true&page=1",
        "last": "https://api.mailersend.com/v1/email-verification/n3k6d1jr1eq50x4v?detailed=true&page=1",
        "prev": null,
        "next": null
      }
    }
  }
}

emails.data.*.result is null until the list is verified, and queued while the email is being verified.

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Create a list

If you want to add a new email verification list, use this POST request:

POST https://api.mailersend.com/v1/email-verification

Request body

{
    "name": "Example List",
    "emails": [
      "example1@mail.com",
      "example2@mail.com"
    ]
}

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\EmailVerificationParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$emailVerificationParams = (new EmailVerificationParams('file.csv'))
    ->setEmailAddresses(['test@mail.com']);

$mailersend->emailVerification->create($emailVerificationParams);

// Optionally start verification immediately or attach to an existing list
$emailVerificationParams = (new EmailVerificationParams('file.csv'))
    ->setEmailAddresses(['test@mail.com'])
    ->setListId('existing_list_id')
    ->setVerify(true);

$mailersend->emailVerification->create($emailVerificationParams);

More examples

import 'dotenv/config';
import { MailerSend, EmailVerification } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const emailVerification = new EmailVerification("My List", [
  "test1@example.com",
  "test2@example.com",
]);

mailerSend.emailVerification.create(emailVerification)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = (EmailVerificationBuilder()
          .name("My Verification List")
          .emails(["test1@example.com", "test2@example.com"])
          .build_create())

response = ms.email_verification.create_verification(request)

More examples

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	options := &mailersend.CreateEmailVerificationOptions{
		Name:   "Email Verification List ",
		Emails: []string{"your@client.com", "your@client.eu"},
	}
	
	_, _, err := ms.EmailVerification.Create(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.EmailVerificationList;

public void createList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        EmailVerificationList list = ms.emailVerification().builder()
			.name("Test email verification")
			.addEmail("info@example.com")
			.addEmail("info1@example.com")
			.addEmail("info2@example.com")
			.create();

        System.out.println(list.id);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email_verification = Mailersend::EmailVerification.new(ms_client)
ms_email_verification.create_a_list(name: "name-your-list", emails: ["example@email.com"])

More examples

Request Parameters

JSON parameters are provided in dot notation

JSON Parameter	Type	Required	Limitations	Details
`name`	`string`	required_without:list_id	Max: `191`
`list_id`	`string`	no	List can't be `verifying`, `paused` or `canceled`.	ID of an existing verification list to append emails to.
`emails`	`array`	yes	Min: `1`, Max: `10000`
`emails.*`	`string`	yes	Max: `320`
`verify`	`boolean`	no		If true, immediately starts verification after upload. Requires enough credits for every email in the list.

Responses

Response Key	Type	Details
data	object	EmailVerification object created.

Valid

Response Code: 201 CREATED
Response Headers:
	content-type: application/json

{
  "data": {
    "id": "n3k6d1jr1eq50x4v",
    "name": "Example List",
    "total": 0,
    "verification_started": null,
    "verification_ended": null,
    "created_at": "2022-07-19T15:11:18.000000Z",
    "updated_at": "2022-07-19T15:11:18.000000Z",
    "status": {
      "name": "uploading",
      "count": 0
    },
    "source": "api",
    "statistics": {
      "valid": 0,
      "catch_all": 0,
      "mailbox_full": 0,
      "role_based": 0,
      "unknown": 0,
      "syntax_error": 0,
      "typo": 0,
      "mailbox_not_found": 0,
      "disposable": 0,
      "mailbox_blocked": 0,
      "failed": 0,
      "not_verified": 0
    }
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - Validation errors

List can't accept emails error

Response Code: 400 Bad Request
Response Headers:
	content-type: application/json

{
  "message": "Can't add more emails to the list in it's current state. #MS40002"
}

Not enough credits error

Response Code: 403 Forbidden
Response Headers:
	content-type: application/json

{
  "message": "You do not have enough credits to perform this operation."
}

Verify a list

If you want to verify an email verification list, use this GET request:

GET https://api.mailersend.com/v1/email-verification/{email_verification_id}/verify

Request parameters

URL parameter	Type	Required	Limitations	Details
`email_verification_id`	`string`	yes

Note: Sending this request while an email list is already being verified (status is verifying) will return an error and will not queue another verification. Also, sending this request when the email list is verified (status is verified) will trigger a new verification.

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->verify('email_verification_id');

More examples

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.verifyList("email_verification_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = (
    EmailVerificationBuilder().email_verification_id("list-id").build_verify_list()
)

response = ms.email_verification.verify_list(request)

More examples

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	
	_, _, err := ms.EmailVerification.Verify(ctx, "email-verification-id")
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.EmailVerificationList;

public void verifyList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        EmailVerificationList list = ms.emailVerification().verifyList("list id");

        System.out.println(list.status.name);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email_verification = Mailersend::EmailVerification.new(ms_client)
ms_email_verification.verify_a_list(email_verification_id: 'your-email-verification-id')

More examples

Responses

Valid

{
  "data": {
    "id": "n3k6d1jr1eq50x4v",
    "name": "Example List",
    "total": 2,
    "verification_started": "2022-07-19T15:24:19.000000Z",
    "verification_ended": null,
    "created_at": "2022-07-19T15:11:18.000000Z",
    "updated_at": "2022-07-19T15:24:19.000000Z",
    "status": {
      "name": "verifying",
      "count": 0
    },
    "source": "api",
    "statistics": {
      "valid": 0,
      "catch_all": 0,
      "mailbox_full": 0,
      "role_based": 0,
      "unknown": 0,
      "syntax_error": 0,
      "typo": 0,
      "mailbox_not_found": 0,
      "disposable": 0,
      "mailbox_blocked": 0,
      "failed": 0,
      "not_verified": 0
    }
  }
}

Still uploading error

Response Code: 400 Bad Request
Response Headers:
	content-type: application/json

{
  "message": "The email addresses are still being uploaded, wait for the upload to finish to continue. #MS40003"
}

Already verifying error

Response Code: 400 Bad Request
Response Headers:
	content-type: application/json

{
  "message": "The email verification list is already being verified. #MS40004"
}

Not enough credits error

Response Code: 403 Forbidden
Response Headers:
	content-type: application/json

{
  "message": "You do not have enough credits to perform this operation."
}

See - Validation errors

Get list results

If you want to get the result for each individual email of an email verification list, use this GET request:

GET https://api.mailersend.com/v1/email-verification/{email_verification_id}/results

Request parameters

URL parameter	Type	Required	Limitations	Details
`email_verification_id`	`string`	yes

Query parameter	Type	Required	Limitations	Details
`page`	`int`	no	Min: `1`
`limit`	`int`	no	Min: `10`, Max: `500`	Default: `25`
`results`	`array`	no
`results.*`	`string`	yes	Must be one of the verification results, `queued`, `not_verified` or `temporary_failure`.

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\EmailVerificationParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->emailVerification->getResults(
        $emailVerificationId = 'email_verification_id',
        $page = 1,
        $limit = 10,
        $results = [
            EmailVerificationParams::TYPO,
            EmailVerificationParams::CATCH_ALL,
        ],
    );

More examples

import 'dotenv/config';
import { EmailVerificationResultType, MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.emailVerification.getListResult("email_verification_id",{
  limit: 10,
  page: 1,
  results: [EmailVerificationResultType.CATCH_ALL, EmailVerificationResultType.DISPOSABLE]
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examples

from mailersend import MailerSendClient, EmailVerificationBuilder

ms = MailerSendClient()

request = EmailVerificationBuilder().email_verification_id("list-id").build_results()

response = ms.email_verification.get_results(request)

More examples

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	options := &mailersend.GetEmailVerificationOptions{
		EmailVerificationId: "email-verification-id",
		Page:                1,
		Limit:               25,
	}

	_, _, err := ms.EmailVerification.GetResults(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examples

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.emailverification.ListVerificationResults;
import com.mailersend.sdk.emailverification.VerificationResult;

public void verifyList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        ListVerificationResults results = ms.emailVerification().verificationResults("list id");

        for (VerificationResult result : results.results) {
            System.out.println(result.address);
            System.out.println(result.result);
        }
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examples

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email_verification = Mailersend::EmailVerification.new(ms_client)
ms_email_verification.get_list_results(email_verification_id: 'your-email-verification-id')

More examples

Responses

Valid

{
  "data": [
    {
      "address": "example1@mail.com",
      "result": "typo"
    },
    {
      "address": "example2@gmail.com",
      "result": "mailbox_not_found"
    }
  ],
  "links": {
    "first": "http:\/\/localhost:8080\/api\/v1\/email-verification\/n3k6d1jr1eq50x4v\/results?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "current_page_url": "http:\/\/localhost:8080\/api\/v1\/email-verification\/n3k6d1jr1eq50x4v\/results?page=1",
    "from": 1,
    "path": "http:\/\/localhost:8080\/api\/v1\/email-verification\/n3k6d1jr1eq50x4v\/results",
    "per_page": 25,
    "to": 2
  }
}

result is null until the list is verified, and queued while the email is being verified.

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Verification results

The possible outcome of an email validation can be grouped in 3 categories: Valid, Risky and Do Not Send.

Valid

Result	Description
`valid`	Email is safe to send.

Risky

Result	Description
`catch_all`	Recipient’s mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person.
`mailbox_full`	Recipient’s inbox is full and may not be able to receive new emails.
`role_based`	Email is role-based and may not be associated with a single, specific person but a group of people.
`unknown`	We are unable to determine if the email is valid or not valid.
`failed`	We could not perform the check due to timeouts. Verify the email by importing a list.

Do Not Send

Result	Description
`syntax_error`	The email address is not valid.
`typo`	The email address has a typo. Correct the email address and retest.
`mailbox_not_found`	Recipient’s inbox does not exist.
`disposable`	The email address is a temporary inbox and should be removed from your lists.
`mailbox_blocked`	The email address’ mailbox is blocked by its service provider due to poor sending practices.

On this page