MailerSend Developers

Recipients

Fetch the email addresses of recipients and other relevant information.

Get recipients

Retrieve the email addresses of recipients using this GET request:

GET https://api.mailersend.com/v1/recipients

Request parameters

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

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

$mailersend->recipients->get(null, $limit = 100, $page = 3);
// Or for a specific domain
$mailersend->recipients->get('domain_id', $limit = 100, $page = 3);

More examplesopen in new window

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

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

mailerSend.email.recipient.list({
  domain_id: "domain_id",
  limit: 10,
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import recipients

api_key = "API key here"

mailer = recipients.NewRecipient(api_key)

mailer.get_recipients()

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.ListRecipientOptions{
		//DomainID: domainID,
		Page:  1,
		Limit: 25,
	}
	
	_, _, err := ms.Recipient.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.mailersend.sdk.util.ApiRecipient;
import com.mailersend.sdk.util.ApiRecipientsList;

public void GetRecipients() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        ApiRecipientsList list = ms.recipients().getRecipients();
        
        for (ApiRecipient recipient : list.recipients) {
            
            System.out.println(recipient.id);
            System.out.println(recipient.email);
        }

    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_recipients = Mailersend::Recipients.new
ms_recipients.list(page: 1, limit: 10)

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "5ee0b174b251345e407c92dc",
      "email": "dsanford@example.net",
      "created_at": "2020-06-10 10:09:56",
      "updated_at": "2020-06-10 10:09:56",
      "deleted_at": ""
    },
    {
      "id": "5ee0b174b251345e407c92dd",
      "email": "konopelski.nina@example.com",
      "created_at": "2020-06-10 10:09:56",
      "updated_at": "2020-06-10 10:09:56",
      "deleted_at": ""
    },
    {
      "id": "5ee0b174b251345e407c92de",
      "email": "hester.howe@example.net",
      "created_at": "2020-06-10 10:09:56",
      "updated_at": "2020-06-10 10:09:56",
      "deleted_at": ""
    }
  ],
  "links": {
    "first": "https:\/\/www.mailersend.io\/api\/v1\/recipients?page=1",
    "last": "https:\/\/www.mailersend.io\/api\/v1\/recipients?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https:\/\/www.mailersend.io\/api\/v1\/recipients",
    "per_page": 25,
    "to": 3,
    "total": 3
  }
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Get a single recipient

Retrieve the information of a single recipient and its domain using this GET request:

GET https://api.mailersend.com/v1/recipients/{recipient_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
recipient_idstringyes
use MailerSend\MailerSend;

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

$mailersend->recipients->find('recipient_id');

More examplesopen in new window

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

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

mailerSend.email.recipient.single("recipient_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import recipients

api_key = "API key here"

mailer = recipients.NewRecipient(api_key)

mailer.get_recipient_by_id("recipient-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()
	
	recipientID := "recipient-id"

	_, _, err := ms.Recipient.Get(ctx, recipientID)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.Recipient;

public void GetSingleRecipient() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        Recipient recipient = ms.recipients().getRecipient("recipient id");
        
        System.out.println(recipient.email);

    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_recipients = Mailersend::Recipients.new
ms_recipients.single(recipient_id: "id124")

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "id": "5ee0b185b251345e407c938e",
    "email": "hauck.sincere@example.net",
    "created_at": "2020-06-10 10:10:13",
    "updated_at": "2020-06-10 10:10:13",
    "deleted_at": "",
    "emails": [],
    "domain": {
      "id": "2j6xej",
      "name": "example.org",
      "dkim": true,
      "spf": true,
      "mx": false,
      "tracking": false,
      "is_verified": true,
      "is_cname_verified": false,
      "is_dns_active": true,
      "is_cname_active": false,
      "is_tracking_allowed": false,
      "has_not_queued_messages": false,
      "not_queued_messages_count": 0,
      "domain_settings": {
        "send_paused": false,
        "track_clicks": true,
        "track_opens": true,
        "track_unsubscribe": true,
        "track_unsubscribe_html": "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe<\/a><\/p>",
        "track_unsubscribe_plain": "Click here to unsubscribe: {{unsubscribe}}",
        "track_content": true,
        "custom_tracking_enabled": false,
        "custom_tracking_subdomain": "email"
      },
      "created_at": "2020-06-10 10:10:13",
      "updated_at": "2020-06-10 10:10:13"
    }
  }
}

Error

Response Code: 404 Not Found

Delete a recipient

Delete the information of a single recipient and its domain using this DELETE request:

DELETE https://api.mailersend.com/v1/recipients/{recipient_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
recipient_idstringyes
use MailerSend\MailerSend;

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

$mailersend->recipients->delete('recipient_id');

More examplesopen in new window

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

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

mailerSend.email.recipient.delete("recipient_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import recipients

api_key = "API key here"

mailer = recipients.NewRecipient(api_key)

mailer.delete_recipient("recipient-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()
	
	recipientID := "recipient-id"
	
	_, err := ms.Recipient.Delete(ctx, recipientID)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.MailerSendResponse;

public void DeleteRecipient() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        MailerSendResponse response = ms.recipients().deleteRecipient("recipient id");
        
        System.out.println(response.responseStatusCode);

    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_recipients = Mailersend::Recipients.new
ms_recipients.delete(recipient_id: "id124")

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 404 Not Found

Get recipients from a suppression list

Blocklist

Retrieve the recipients in a blocklist of an account or domain by passing the blocklist ID with this GET request:

GET https://api.mailersend.com/v1/suppressions/blocklist

Request parameters

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

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

$mailersend->blocklist->getAll('domain_id', 15);

More examplesopen in new window

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

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

mailerSend.email.recipient.blockList(
  { domain_id: "domain_id", },
  BlockListType.BLOCK_LIST
)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import recipients

api_key = "API key here"

mailer = recipients.NewRecipient(api_key)

mailer.get_recipients_from_blocklist("domain-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()

	listOptions := &mailersend.SuppressionOptions{
		DomainID: "domain-id",
		Page:     1,
		Limit:    25,
	}

	// List Block List Recipients 
	_, _, err := ms.Suppression.ListBlockList(ctx, listOptions)
	if err != nil {
		log.Fatal(err)
	}

	// List Hard Bounces 
	_, _, _ = ms.Suppression.ListHardBounces(ctx, listOptions)

	// List Spam Complaints 
	_, _, _ = ms.Suppression.ListSpamComplaints(ctx, listOptions)
	
	// List Unsubscribes
	_, _, _ = ms.Suppression.ListUnsubscribes(ctx, listOptions)


}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.BlocklistItem;
import com.mailersend.sdk.recipients.BlocklistListResponse;
import com.mailersend.sdk.recipients.SuppressionItem;
import com.mailersend.sdk.recipients.SuppressionList;

public void GetRecipientsFromSuppressionList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        BlocklistListResponse blocklist = ms.recipients().suppressions().getBlocklist();
        
        for (BlocklistItem item : blocklist.items) {
            
            System.out.println(item.id);
            System.out.println(item.pattern);
            System.out.println(item.type);
        }
        
        SuppressionList hardBounces = ms.recipients().suppressions().getHardBounces();
        
        for (SuppressionItem item : hardBounces.items) {
            
            System.out.println(item.id);
            System.out.println(item.recipient.email);
        }
        
        SuppressionList spamComplaints = ms.recipients().suppressions().getSpamComplaints();
        
        for (SuppressionItem item : spamComplaints.items) {
            
            System.out.println(item.id);
            System.out.println(item.recipient.email);
        }
        
        SuppressionList unsubscribes = ms.recipients().suppressions().getUnsubscribes();
        
        for (SuppressionItem item : unsubscribes.items) {
            
            System.out.println(item.id);
            System.out.println(item.recipient.email);
        }

    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_suppressions = Mailersend::Suppressions.new

// List from Blocklist 
ms_suppressions.get_from_blocklist(domain_id: "xxx2241ll")

// List from Hard Bounces
ms_suppressions.get_hard_bounces(domain_id: "xxx2241ll")

// List from Spam Complaints
ms_suppressions.get_spam_complaints(domain_id: "xxx2241ll")

// List from Unsubscribers
ms_suppressions.get_unsubscribes(domain_id: "xxx2241ll")

More examplesopen in new window

Responses

Response keyTypeDetails
data.*object[]Array of recipients in the blocklist.
data.*.domainobjectIncludes data of the domain related to the blocklist. When this property is null, the blocklist is attached to an account instead of a domain.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f0176881bf3d1fe618daae",
      "type": "pattern",
      "pattern": ".*@example.net",
      "domain": {
        "id": "7nxe3yjmeq28vp0k",
        "name": "mailersend.com",
        "created_at": "2021-07-15T11:04:44.000000Z",
        "updated_at": "2021-07-15T11:04:45.000000Z"
      },
      "created_at": "2021-07-14T07:04:01.298000Z",
      "updated_at": "2021-07-14T07:04:01.298000Z"
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Hard Bounces

Retrieve the hard bounced recipients of an account or domain by passing its ID with this GET request:

GET https://api.mailersend.com/v1/suppressions/hard-bounces

Request parameters

Query parameterTypeRequiredLimitationsDetails
domain_idstringno
limitintnoMin: 10, Max: 100Default: 25
pageintno

Responses

Response keyTypeDetails
data.*object[]Array of hard bounces.
data.*.recipientobjectRecipient related to the hard bounce.
data.*.recipient.domainobjectDomain related to the hard bounce.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f0176881bf3d1fe618dab0",
      "reason": "Unknown reason",
      "created_at": "2021-06-29T07:04:01.298000Z",
      "recipient": {
        "id": "60f0176881bf3d1fe618daaf",
        "email": "test@example.com",
        "created_at": "2021-06-29T07:04:01.298000Z",
        "updated_at": "2021-06-29T07:04:01.298000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailersend.com",
          "created_at": "2021-07-15T11:04:44.000000Z",
          "updated_at": "2021-07-15T11:04:45.000000Z"
        }
      }
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Spam Complaints

Retrieve the recipients who have made a spam complaint for an account or domain by passing its ID with this GET request:

GET https://api.mailersend.com/v1/suppressions/spam-complaints

Request parameters

Query parameterTypeRequiredLimitationsDetails
domain_idstringno
limitintnoMin: 10, Max: 100Default: 25
pageintno

Responses

Response keyTypeDetails
data.*object[]Array of spam complaints.
data.*.recipientobjectRecipient related to the spam complaint.
data.*.recipient.domainobjectDomain related to the spam complaint.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f0176981bf3d1fe618dab4",
      "created_at": "2021-06-29T07:04:01.298000Z",
      "recipient": {
        "id": "60f0176881bf3d1fe618dab3",
        "email": "pmcdermott@example.net",
        "created_at": "2021-06-29T07:04:01.298000Z",
        "updated_at": "2021-06-29T07:04:01.298000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailersend.com",
          "created_at": "2021-07-15T11:04:44.000000Z",
          "updated_at": "2021-07-15T11:04:45.000000Z"
        }
      }
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Unsubscribes

Retrieve the unsubscribed recipients for an account or domain by passing its ID with this GET request:

GET https://api.mailersend.com/v1/suppressions/unsubscribes

Request parameters

Query parameterTypeRequiredLimitationsDetails
domain_idstringno
limitintnoMin: 10, Max: 100Default: 25
pageintno

Responses

Response keyTypeDetails
data.*object[]Array of unsubscribes.
data.*.recipientobjectRecipient related to the unsubscribe.
data.*.recipient.domainobjectDomain related to the unsubscribe.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f0176881bf3d1fe618dab2",
      "reason": "NEVER_SIGNED",
      "readable_reason": "I never signed up for this mailing list",
      "recipient": {
        "id": "60f0176881bf3d1fe618dab1",
        "email": "taya86@example.com",
        "created_at": "2021-06-29T07:04:01.298000Z",
        "updated_at": "2021-06-29T07:04:01.298000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailersend.com",
          "created_at": "2021-07-15T11:04:44.000000Z",
          "updated_at": "2021-07-15T11:04:45.000000Z"
        }
      },
      "created_at": "2021-06-29T07:04:01.298000Z"
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

On Hold List

Retrieve on hold recipients for an account or domain by passing its ID with this GET request:

GET https://api.mailersend.com/v1/suppressions/on-hold-list

Request parameters

Query parameterTypeRequiredLimitationsDetails
domain_idstringno
limitintnoMin: 10, Max: 100Default: 25
pageintno

Responses

Response keyTypeDetails
data.*object[]Array of on hold list.
data.*.recipientobjectRecipient on hold.
data.*.recipient.domainobjectDomain related to the on hold recipient.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "64c760a33e2db0f6340f4710",
      "created_at": "2023-07-15T19:22:37.579000Z",
      "on_hold_until": "2023-07-18T19:22:37.579000Z",
      "email": "shanna.fadel@example.net",
      "recipient": {
        "id": "64c760a33e2db0f6340f470f",
        "email": "shanna.fadel@example.net",
        "created_at": "2023-07-15T19:22:37.579000Z",
        "updated_at": "2023-07-15T19:22:37.579000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailerlite.com",
          "created_at": "2023-07-31T07:18:59.000000Z",
          "updated_at": "2023-07-31T07:19:23.000000Z"
        }
      }
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Add recipients to a suppression list

Blocklist

Add a recipient to a blocklist with this POST request:

POST https://api.mailersend.com/v1/suppressions/blocklist

Request Body

{
    "domain_id": "83gwk2j7zqz1nxyd",
    "recipients": [
      "test@example.com"
    ],
    "patterns": [
      ".*@example.com"
    ]
}

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\BlocklistParams;

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

$params = (new BlocklistParams())
    ->setDomainId('domain_id')
    ->setRecipients(['recipient_one', 'recipient_two'])
    ->setPatterns(['pattern_one', 'pattern_two']);

$mailersend->blocklist->create($params);

More examplesopen in new window

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

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

mailerSend.email.recipient.blockRecipients({
  domain_id: 'domain_id',
  recipients: [
    "test@example.com"
  ]
}, BlockListType.BLOCK_LIST)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import recipients

api_key = "API key here"

mailer = recipients.NewRecipient(api_key)

recipient_list = [
    'blocked@client.com'
]

mailer.add_to_blocklist("domain-id", recipients=recipient_list)

More examplesopen in new window

package main

import (
	"context"
	"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()

	// Add Recipient to Block List
	createSuppressionBlockOptions := &mailersend.CreateSuppressionBlockOptions{
		DomainID:   "domain-id",
		Recipients: []string{"test@example.com"},
		Patterns: []string{".*@example.com"},
	}
	
	_, _, _ = ms.Suppression.CreateBlock(ctx, createSuppressionBlockOptions)

	// Add Recipient to Hard Bounces
	createSuppressionHardBounceOptions := &mailersend.CreateSuppressionOptions{
		DomainID:   "domain-id",
		Recipients: []string{"test@example.com"},
	}

	_, _, _ = ms.Suppression.CreateHardBounce(ctx, createSuppressionHardBounceOptions)

	// Add Recipient to Spam Complaints
	createSuppressionSpamComplaintsOptions := &mailersend.CreateSuppressionOptions{
		DomainID:   "domain-id",
		Recipients: []string{"test@example.com"},
	}

	_, _, _ = ms.Suppression.CreateHardBounce(ctx, createSuppressionSpamComplaintsOptions)

	// Add Recipient to Unsubscribes
	createSuppressionUnsubscribesOptions := &mailersend.CreateSuppressionOptions{
		DomainID:   "domain-id",
		Recipients: []string{"test@example.com"},
	}
	
	_, _, _ = ms.Suppression.CreateHardBounce(ctx, createSuppressionUnsubscribesOptions)

}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.BlocklistItem;
import com.mailersend.sdk.recipients.BlocklistListResponse;
import com.mailersend.sdk.recipients.SuppressionItem;
import com.mailersend.sdk.recipients.SuppressionList;

public void AddRecipientsToSuppressionList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        // blocklist
        ms.recipients().suppressions().addBuilder().pattern(".*@example.com");
        ms.recipients().suppressions().addBuilder().recipient("test@example.com");
        BlocklistItem[] items = ms.recipients().suppressions().addBuilder().addToBlocklist();
        
        for (BlocklistItem item : items) {
            
            System.out.println(item.id);
        }
        
        
        // hard bounces
        ms.recipients().suppressions().addBuilder().recipient("test@example.com");
        ms.recipients().suppressions().addBuilder().domainId(TestHelper.domainId);
        SuppressionList list = ms.recipients().suppressions().addBuilder().addRecipientsToHardBounces();
        
        for (SuppressionItem item : list.items) {
            
            System.out.println(item.id);
        }
        
        
        // spam complaints
        ms.recipients().suppressions().addBuilder().recipient("test@example.com");
        ms.recipients().suppressions().addBuilder().domainId(TestHelper.domainId);
        list = ms.recipients().suppressions().addBuilder().addRecipientsToSpamComplaints();
        
        for (SuppressionItem item : list.items) {
            
            System.out.println(item.id);
        }
        
        
        // unsubscribes
        ms.recipients().suppressions().addBuilder().recipient("test@example.com");
        ms.recipients().suppressions().addBuilder().domainId(TestHelper.domainId);
        list = ms.recipients().suppressions().addBuilder().addRecipientsToUnsubscribes();
        
        for (SuppressionItem item : list.items) {
            
            System.out.println(item.id);
        }

    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_suppressions = Mailersend::Suppressions.new

// Add Recipient to Block List using recipients
ms_suppressions.add_to_blocklist(domain_id: "xxx2241ll", recipients: ["blocked@client.com"])

// Add Recipient to Block List using patterns
ms_suppressions.add_to_blocklist(domain_id: "xxx2241ll", patterns: ["*@client.com"])

// Add Recipient to Hard Bounces
ms_suppressions.add_to_hard_bounces(domain_id: "xxx2241ll", recipients: ["bounced@client.com"])

// Add Recipient to Spam Complaints
ms_suppressions.add_to_spam_complaints(domain_id: "xxx2241ll", recipients: ["bounced@client.com"])

// Add Recipient to Unsubscribes
ms_suppressions.add_to_unsubscribers(domain_id: "xxx2241ll", recipients: ["bounced@client.com"])

More examplesopen in new window

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringyes
recipients[]string[]noIf patterns is not defined, this property is required.
recipients.*stringyesMust be an email.
patterns[]string[]noIf recipients is not defined, this property is required.
patterns.*stringyes

Responses

Response keyTypeDetails
data.*object[]Array of blocklist entries created.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f198790542d97fb66dfe52",
      "type": "exact",
      "pattern": "test@example.com",
      "created_at": "2021-07-16T14:32:25.457000Z",
      "updated_at": "2021-07-16T14:32:25.457000Z"
    },
    {
      "id": "60f198790542d97fb66dfe53",
      "type": "pattern",
      "pattern": ".*@example.com",
      "created_at": "2021-07-16T14:32:25.476000Z",
      "updated_at": "2021-07-16T14:32:25.476000Z"
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Hard Bounces

Add a hard bounce for one or more recipients with this POST request:

POST https://api.mailersend.com/v1/suppressions/hard-bounces

Request Body

{
  "domain_id": "83gwk2j7zqz1nxyd",
  "recipients": [
    "test@example.com"
  ]
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringyes
recipients[]string[]yes
recipients.*stringyesMust be an email.

Responses

Response keyTypeDetails
data.*object[]Array of hard bounces created.
data.*.recipientobjectRecipient related to the hard bounce.
data.*.domain.domainobjectDomain related to the hard bounce.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f1a0195c14080bbc606293",
      "reason": null,
      "created_at": "2021-07-16T15:04:57.939000Z",
      "recipient": {
        "id": "60f1a0195c14080bbc606292",
        "email": "test@example.com",
        "created_at": "2021-07-16T15:04:57.888000Z",
        "updated_at": "2021-07-16T15:04:57.907000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailersend.com",
          "created_at": "2021-07-15T11:04:44.000000Z",
          "updated_at": "2021-07-15T11:04:45.000000Z"
        }
      }
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Spam Complaints

Add a spam complaint for one or more recipients with this POST request:

POST https://api.mailersend.com/v1/suppressions/spam-complaints

Request Body

{
  "domain_id": "83gwk2j7zqz1nxyd",
  "recipients": [
    "test@example.com"
  ]
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringyes
recipients[]string[]yes
recipients.*stringyesMust be an email.

Responses

Response keyTypeDetails
data.*object[]Array of spam complaints created.
data.*.recipientobjectRecipient related to the spam complaint.
data.*.recipient.domainobjectDomain related to the spam complaint.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f1a9fa33d68f023f2d3972",
      "created_at": "2021-07-16T15:47:06.280000Z",
      "recipient": {
        "id": "60f1a0195c14080bbc606292",
        "email": "test@example.com",
        "created_at": "2021-07-16T15:04:57.888000Z",
        "updated_at": "2021-07-16T15:47:06.244000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailersend.com",
          "created_at": "2021-07-15T11:04:44.000000Z",
          "updated_at": "2021-07-15T11:04:45.000000Z"
        }
      }
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Unsubscribes

Set one or more recipients as unsubscribed with this POST request:

POST https://api.mailersend.com/v1/suppressions/unsubscribes

Request Body

{
  "domain_id": "83gwk2j7zqz1nxyd",
  "recipients": [
    "test@example.com"
  ]
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringyes
recipients[]string[]yes
recipients.*stringyesMust be an email.

Responses

Response keyTypeDetails
data.*object[]Array of unsubscribe entries created.
data.*.recipientobjectRecipient related to the unsubscribe.
data.*.recipient.domainobjectDomain related to the unsubscribe.

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "id": "60f53a20506faf239d471ff2",
      "reason": null,
      "readable_reason": null,
      "recipient": {
        "id": "60f1a0195c14080bbc606292",
        "email": "test@example.com",
        "created_at": "2021-07-16T15:04:57.888000Z",
        "updated_at": "2021-07-19T08:38:56.243000Z",
        "deleted_at": "",
        "domain": {
          "id": "7nxe3yjmeq28vp0k",
          "name": "mailersend.com",
          "created_at": "2021-07-15T11:04:44.000000Z",
          "updated_at": "2021-07-15T11:04:45.000000Z"
        }
      },
      "created_at": "2021-07-19T08:38:56.283000Z"
    }
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Delete recipients from a suppression list

Blocklist

Delete one or more blocklist entries with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/blocklist

Request Body

To delete specific entries:

{
  "ids": [
    "60f198790542d97fb66dfe52",
    "60f198790542d97fb66dfe53"
  ]
}

To delete all entries:

{
  "all": true
}

use MailerSend\MailerSend;

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

// Delete specific instances
$mailersend->blocklist->delete(['id_one', 'id_two']);

// or delete all
$mailersend->blocklist->delete(null, true);

// You can also specify the domain
$mailersend->blocklist->delete(['id'], false, 'domain_id');

More examplesopen in new window

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

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

mailerSend.email.recipient.delBlockListRecipients(
  ["recipient_id", "recipient_id"],
  BlockListType.BLOCK_LIST
)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import recipients

api_key = "API key here"

mailer = recipients.NewRecipient(api_key)

recipient_list = [
    "your@client.com"
]

mailer.delete_from_blocklist("domain-id", recipient_list)

More examplesopen in new window

package main

import (
	"context"
	"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()

	domainID := "domain-id"

	// Delete All {type}
	
	// mailersend.BlockList 
	// mailersend.HardBounces 
	// mailersend.SpamComplaints 
	// mailersend.Unsubscribes
	
	_, _ = ms.Suppression.DeleteAll(ctx, domainID, mailersend.Unsubscribes)
	
	// Delete 

	deleteSuppressionOption := &mailersend.DeleteSuppressionOptions{
		DomainID: domainID,
		Ids:      []string{"suppression-id"},
	}

	_, _ = ms.Suppression.Delete(ctx, deleteSuppressionOption, mailersend.Unsubscribes)


}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.recipients.BlocklistItem;
import com.mailersend.sdk.recipients.BlocklistListResponse;
import com.mailersend.sdk.recipients.SuppressionItem;
import com.mailersend.sdk.recipients.SuppressionList;

public void DeleteRecipientsFromSuppressionList () {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
        // delete from blocklist
        BlocklistListResponse blocklist = ms.recipients().suppressions().getBlocklist();
        
        if (blocklist.items.length == 0) {
            
            fail();
        }
        
        String itemId = blocklist.items[0].id;
        
        MailerSendResponse response = ms.recipients().suppressions().deleteBlocklistItems(new String[] { itemId });
        
        System.out.println(response.responseStatusCode);
        
        
        // delete from hard bounces
        SuppressionList hardBounces = ms.recipients().suppressions().getHardBounces();
        
        if (hardBounces.items.length == 0) {
            
            fail();
        }
        
        itemId = hardBounces.items[0].id;
        
        response = ms.recipients().suppressions().deleteHardBouncesItems(new String[] { itemId });
        
        System.out.println(response.responseStatusCode);
        
        
        // delete from spam complaints
        SuppressionList spamComplaints = ms.recipients().suppressions().getSpamComplaints();
        
        if (spamComplaints.items.length == 0) {
            
            fail();
        }
        
        itemId = spamComplaints.items[0].id;
        
        response = ms.recipients().suppressions().deleteSpamComplaintsItems(new String[] { itemId });
        
        System.out.println(response.responseStatusCode);
        

        // delete from unsubscribes
        SuppressionList unsubscribes = ms.recipients().suppressions().getUnsubscribes();
        
        if (unsubscribes.items.length == 0) {
            
            fail();
        }
        
        itemId = unsubscribes.items[0].id;
        
        response = ms.recipients().suppressions().deleteUnsubscribesItems(new String[] { itemId });
        
        System.out.println(response.responseStatusCode);

    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_suppressions = Mailersend::Suppressions.new

// Delete from Block List
ms_suppressions.delete_from_blocklist(domain_id: 'yourdomainid', ids: ["xxx2241ll"])

// Delete from Hard Bounces
ms_suppressions.delete_from_hard_bounces(domain_id: 'yourdomainid', ids: ["xxx2241ll"])

// Delete from Spam Complaints
ms_suppressions.delete_from_spam_complaints(domain_id: 'yourdomainid', ids: ["xxx2241ll"])

// Delete from Unsubscribes
ms_suppressions.delete_from_unsubscribers(domain_id: 'yourdomainid', ids: ["xxx2241ll"])

More examplesopen in new window

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringno
idsstring[]noRequired if all is not defined.
allbooleannoRequired if ids is not defined.

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "ids.0": [
      "The selected ids.0 is invalid."
    ],
    "ids.1": [
      "The selected ids.1 is invalid."
    ]
  }
}

See - Validation errors

Hard Bounces

Delete one or more hard bounces from recipients by passing the hard bounces IDs with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/hard-bounces

Request Body

To delete specific entries:

{
  "ids": [
    "60d0563fd4fb3212e2065522",
    "60ae0999c3da7c275f3b5589"
  ]
}

To delete all entries:

{
  "all": true
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringno
idsstring[]noRequired if all is not defined.
allbooleannoRequired if ids is not defined.

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "ids.0": [
      "The selected ids.0 is invalid."
    ],
    "ids.1": [
      "The selected ids.1 is invalid."
    ]
  }
}

See - Validation errors

Spam Complaints

Delete one or more spam complaints from recipients by providing the spam complaint IDs with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/spam-complaints

Request Body

To delete specific entries:

{
  "ids": [
    "60d32115d14907786d7fdd42",
    "60ae0999c3da7c275f3b558e"
  ]
}

To delete all entries:

{
  "all": true
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringno
idsstring[]noRequired if all is not defined.
allbooleannoRequired if ids is not defined.

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "ids.0": [
      "The selected ids.0 is invalid."
    ],
    "ids.1": [
      "The selected ids.1 is invalid."
    ]
  }
}

See - Validation errors

Unsubscribes

Delete one or more unsubscribe entries from recipients by passing the unsubscribe IDs with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/unsubscribes

Request Body

To delete specific entries:

{
  "ids": [
    "60d3169d8dc7b007f356d142",
    "60ae0999c3da7c275f3b558b"
  ]
}

To delete all entries:

{
  "all": true
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
domain_idstringno
idsstring[]noRequired if all is not defined.
allbooleannoRequired if ids is not defined.

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "ids.0": [
      "The selected ids.0 is invalid."
    ],
    "ids.1": [
      "The selected ids.1 is invalid."
    ]
  }
}

See - Validation errors

On Hold List

Delete one or more recipient entries from on hold list by passing the on hold list IDs with this DELETE request:

DELETE https://api.mailersend.com/v1/suppressions/on-hold-list

Request Body

To delete specific entries:

{
  "ids": [
    "64c760a33e2db0f6340f4710",
    "64c760a33e2db0f6340f470e"
  ]
}

To delete all entries:

{
  "all": true
}

Request parameters

JSON parameters are provided in dot notation.

JSON parameterTypeRequiredLimitationsDetails
idsstring[]noRequired if all is not defined.
allbooleannoRequired if ids is not defined.

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "ids.0": [
      "The selected ids.0 is invalid."
    ],
    "ids.1": [
      "The selected ids.1 is invalid."
    ]
  }
}

See - Validation errors

Last Updated: 5/20/2025, 9:34:47 AM