MailerSend Developers

Email Verification

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 parameterTypeRequiredLimitationsDetails
emailstringyes

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

ResultDescription
validEmail is safe to send.

Risky

ResultDescription
catch_allRecipient's mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person.
mailbox_fullRecipient’s inbox is full and may not be able to receive new emails.
role_basedEmail is role-based and may not be associated with a single, specific person but a group of people.
unknownWe are unable to determine if the email is valid or not valid.
failedWe could not perform the check due to timeouts. Verify the email by importing a list.

Do Not Send

ResultDescription
syntax_errorThe email address is not valid.
typoThe email address has a typo. Correct the email address and retest.
mailbox_not_foundRecipient’s inbox does not exist.
disposablesThe email address is a temporary inbox and should be removed from your lists.
mailbox_blockedThe 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 parameterTypeRequiredLimitationsDetails
emailstringyes

Responses

Valid

{
  "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 parameterTypeRequiredLimitationsDetails
email_verification_idstringyes

Check verification status

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

StatusDescription
queuedThe verification process is ongoing.
completedThe verification process has finished successfully.
failedThe verification process has run into an internal error.

Responses

Valid

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

Get all lists

Get all email verifications lists with this GET request:

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

Request parameters

Query parameterTypeRequiredLimitationsDetails
pageintno
limitintnoMin: 10, Max: 100Default: 25
use MailerSend\MailerSend;

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

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

More examplesopen in new window

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 examplesopen in new window

from mailersend import email_verification

api_key = "API key here"

mailer = email_verification.NewEmailVerification(api_key)

mailer.get_all_lists()

More examplesopen in new window

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 examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailsend.sdk.emailverification.EmailVerificationList;
import com.mailsend.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 examplesopen in new window

require "mailersend-ruby"

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

More examplesopen in new window

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
      }
    }
  ],
  "links": {
    "first": "http:\/\/localhost:8080\/api\/v1\/email-verification?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "http:\/\/localhost:8080\/api\/v1\/email-verification",
    "per_page": "10",
    "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 parameterTypeRequiredLimitationsDetails
email_verification_idstringyes

Check verification status

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

StatusDescription
uploadingThe email addresses are being uploaded to our system.
createdThe list has been created and is ready to be verified.
verifyingThe verification process is ongoing.
verifiedThe verification process has finished successfully.
failedThe verification process has run into an internal error.

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');

More examplesopen in new window

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 examplesopen in new window

from mailersend import email_verification

api_key = "API key here"

mailer = email_verification.NewEmailVerification(api_key)

email_verification_list_id = 123456

mailer.get_list(email_verification_list_id)

More examplesopen in new window

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 examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailsend.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 examplesopen in new window

require "mailersend-ruby"

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

More examplesopen in new window

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
    }
  }
}

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

More examplesopen in new window

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

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

const emailVerification = new EmailVerification()
  .setName("List example")
  .setEmails([
    "info@mailersend.com",
    "test@mailersend.com"
  ]);

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

More examplesopen in new window

from mailersend import email_verification

api_key = "API key here"

mailer = email_verification.NewEmailVerification(api_key)

name = "My List"
emails = [
    "some@email.com",
    "another@email.com"
]

mailer.create_list(name, emails)

More examplesopen in new window

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 examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailsend.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 examplesopen in new window

require "mailersend-ruby"

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

More examplesopen in new window

Request Parameters

JSON parameters are provided in dot notation

JSON ParameterTypeRequiredLimitationsDetails
namestringyes
emailsstringyesMin: 1
emails.*stringyesMust not exceed 191 characters

Supported file types

File typeExtensions
Text files.csv, .txt

Responses

Response KeyTypeDetails
dataobjectEmailVerification 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
    }
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - Validation errors

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 parameterTypeRequiredLimitationsDetails
email_verification_idstringyes

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

use MailerSend\MailerSend;

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

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

More examplesopen in new window

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 examplesopen in new window

from mailersend import email_verification

api_key = "API key here"

mailer = email_verification.NewEmailVerification(api_key)

email_verification_list_id = 123456

mailer.verify_list(email_verification_list_id)

More examplesopen in new window

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 examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailsend.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 examplesopen in new window

require "mailersend-ruby"

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

More examplesopen in new window

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
    }
  }
}

Still uploading error

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

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

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 parameterTypeRequiredLimitationsDetails
email_verification_idstringyes
Query parameterTypeRequiredLimitationsDetails
pageintno
limitintnoMin: 10, Max: 100Default: 25
resultsarrayno
results.*stringyesMust be one of the verification results.
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 examplesopen in new window

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,
  result: [EmailVerificationResultType.CATCH_ALL, EmailVerificationResultType.DISPOSABLE]
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import email_verification

api_key = "API key here"

mailer = email_verification.NewEmailVerification(api_key)

email_verification_list_id = 123456

mailer.get_list_results(email_verification_list_id)

More examplesopen in new window

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 examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailsend.sdk.emailverification.ListVerificationResults;
import com.mailsend.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 examplesopen in new window

require "mailersend-ruby"

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

More examplesopen in new window

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?1=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "http:\/\/localhost:8080\/api\/v1\/email-verification\/n3k6d1jr1eq50x4v\/results",
    "per_page": 25,
    "to": 2
  }
}

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

ResultDescription
validEmail is safe to send.

Risky

ResultDescription
catch_allRecipient's mail server will accept emails to this address, but we cannot guarantee this email address belongs to a person.
mailbox_fullRecipient’s inbox is full and may not be able to receive new emails.
role_basedEmail is role-based and may not be associated with a single, specific person but a group of people.
unknownWe are unable to determine if the email is valid or not valid.

Do Not Send

ResultDescription
syntax_errorThe email address is not valid.
typoThe email address has a typo. Correct the email address and retest.
mailbox_not_foundRecipient’s inbox does not exist.
disposablesThe email address is a temporary inbox and should be removed from your lists.
mailbox_blockedThe email address’ mailbox is blocked by its service provider due to poor sending practices.
Last Updated: