Inbound routing

Get a list of inbound routes

If you want to retrieve information about multiple inbound routes, use this GET request:

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

Request parameters

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

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

$mailersend->inbound->getAll($domainId = 'domainId', $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.email.inbound.list()
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import inbound_routing

api_key = "API key here"

mailer = inbound_routing.NewInbound(api_key)

print(mailer.get_inbound_routes())

More examplesopen in new window

package main

import (
	"context"

	"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.TODO()

	domainID := "domain-id"

	listOptions := &mailersend.ListInboundOptions{
		DomainID: domainID,
	}
	
	_, _, _ = ms.Inbound.List(ctx, listOptions)
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.inboundroutes.InboundRoute;
import com.mailersend.sdk.inboundroutes.InboundRoutesList;

public void getInboundRoutes() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        InboundRoutesList routes = ms.inboundRoutes().getRoutes();

        for (InboundRoute route : routes.routes) {
            System.out.println(route.id);
        }

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.get_inbound_routes

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Headers:
	Content-Type: application/json
{
  "data": [
    {
      "id": "v57gn2j67qlr6z4d",
      "name": "Test name",
      "address": "imxbfppzn7cbhak9lef5@inbound.mailersend.net",
      "domain": "test.mailersend.com",
      "dns_checked_at": null,
      "enabled": true,
      "filters": [
        {
          "type": "catch_recipient",
          "key": null,
          "comparer": "equal",
          "value": "test"
        },
        {
          "type": "match_all",
          "key": null,
          "comparer": null,
          "value": null
        }
      ],
      "forwards": [
        {
          "type": "webhook",
          "value": "https:\/\/yourapp.com\/hook",
          "secret": "jYhafQeTihgw0qWclkUA7cbqTG3Zfh2j"
        }
      ],
      "priority": 100,
      "mxValues": {
        "priority": 10,
        "target": "inbound.mailersend.net"
      }
    }
  ]
}

Error

Response Code: 404 Not Found

Get a single inbound route

If you want to retrieve a single inbound route, use this GET request:

GET https://api.mailersend.com/v1/inbound/{inbound_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
inbound_idstringyes
use MailerSend\MailerSend;

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

$mailersend->inbound->find('inboundId');

More examplesopen in new window

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

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

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

More examplesopen in new window

from mailersend import inbound_routing

api_key = "API key here"

mailer = inbound_routing.NewInbound(api_key)

print(mailer.get_inbound_by_id("inbound-id"))

More examplesopen in new window

package main

import (
	"context"

	"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.TODO()

	inboundID := "inbound-id"

	_, _, _ = ms.Inbound.Get(ctx, inboundID)
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.inboundroutes.InboundRoute;

public void getInboundRoute() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        InboundRoute route = ms.inboundRoutes().getRoute("inbound route id");

        System.out.println(route.id);
        System.out.println(route.name);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.get_single_route(inbound_id: 'idofroute12412')

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Headers:
	Content-Type: application/json
{
  "data": {
    "id": "v57gn2j67qlr6z4d",
    "name": "Test name",
    "address": "imxbbppzn7cbhak9lef5@inbound.mailersend.net",
    "domain": "test.mailersend.com",
    "dns_checked_at": null,
    "enabled": true,
    "filters": [
      {
        "type": "catch_recipient",
        "key": null,
        "comparer": "equal",
        "value": "test"
      },
      {
        "type": "match_all",
        "key": null,
        "comparer": null,
        "value": null
      }
    ],
    "forwards": [
      {
        "id": "v57gn2j67qlr6z4d",
        "type": "webhook",
        "value": "https:\/\/yourapp.com\/hook",
        "secret": "jYhafQeTiZgw0qWxlkUA7cbqTG3Zfh2j"
      }
    ],
    "priority": 100,
    "mxValues": {
      "priority": 10,
      "target": "inbound.mailersend.net"
    }
  }
}

Error

Response Code: 404 Not Found

Add an inbound route

If you want to add a new inbound route to a domain, use this POST request:

POST https://api.mailersend.com/v1/inbound

Request body

{
    "domain_id": "7nxe3yjmeq28vp0k",
    "name": "Test name",
    "domain_enabled": true,
    "inbound_domain": "test.mailersend.com",
    "inbound_address": "test@inbound.mailersend.net",
    "inbound_subdomain": "inbound",
    "inbound_priority": 100,
    "match_filter": {
      "type": "match_all"
    },
    "catch_filter": {
      "type": "catch_recipient",
      "filters": [
        {
          "comparer": "equal",
          "value": "test"
          }
      ]
    },
    "forwards": [
      {
        "type": "webhook",
        "value": "https://www.mailersend.com/hook"
      }
    ]
}
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Inbound;
use \MailerSend\Helpers\Builder\CatchFilter;
use \MailerSend\Helpers\Builder\MatchFilter;
use \MailerSend\Helpers\Builder\Forward;
use \MailerSend\Helpers\Builder\Filter;
use \MailerSend\Common\Constants;

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

$mailersend->inbound->create(
    (new Inbound('domainId', 'name', true))
        ->setInboundDomain('inboundDomain')
        ->setCatchFilter(
            (new CatchFilter(Constants::TYPE_CATCH_RECIPIENT)
                ->addFilter(new Filter(Constants::COMPARER_EQUAL, 'test@mailersend.com'))))
        ->setMatchFilter(
            (new MatchFilter(Constants::TYPE_MATCH_SENDER))
                ->addFilter(new Filter(Constants::COMPARER_EQUAL, 'sender@mailersend.com', 'sender')))
        ->addForward(new Forward(Constants::COMPARER_EQUAL, 'value'))
);

More examplesopen in new window

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

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

const inbound = new Inbound()
  .setDomainId('domain_id')
  .setName('inbound test')
  .setDomainEnabled(true)
  .setMatchFilter({
    type: InboundFilterType.MATCH_ALL,
  })
  .setForwards([
    {
      type: "webhook",
      value: "https://www.yourdomain.com/hook"
    }
  ]);

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

More examplesopen in new window

from mailersend import inbound_routing

mailer = inbound_routing.NewInbound()

options = {}

_catch_filter = {
    "type": "catch_recipient",
    "filters": [
        {
            "comparer": "equal",
            "value": "test"
        }
    ]
}

_match_filter = {
    "type": "match_all"
}

_forwards = [
    {
        "type": "webhook",
        "value": "https://www.mailersend.com/hook"
    }
]
mailer.set_name("Example route", options)
mailer.set_domain_enabled(True, options)
mailer.set_inbound_domain("test.mailersend.com", options)
mailer.set_catch_filter(_catch_filter, options)

print(mailer.add_inbound_route())

More examplesopen in new window

package main

import (
	"context"

	"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.TODO()

	domainID := "domain-id"

	createOptions := &mailersend.CreateInboundOptions{
		DomainID:      domainID,
		Name:          "Example Route",
		DomainEnabled: *mailersend.Bool(false),
		MatchFilter: &mailersend.MatchFilter{
			Type: "match_all",
		},
		CatchFilter: &mailersend.CatchFilter{},
		Forwards: []mailersend.Forwards{
			{
				Type:  "webhook",
				Value: "https://example.com",
			},
		},
	}

	_, _, _ = ms.Inbound.Create(ctx, createOptions)
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.inboundroutes.Forward;

public void createInboundRoute() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {

        Forward forward = new Forward();
        forward.type = "webhook";
        forward.value = "https://example-domain.com";
        forward.secret = "asdfgh";
    
        ms.inboundRoutes().builder()
            .domainId("domain id")
            .name("Test inbound name")
            .domainEnabled(false)
            .matchFilter("match_all")
            .forwards(new Forward[] { forward })
            .addRoute();

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.settings =
  {
    'domain_id' => 'yourdomainid',
    'name' => 'inbound_name',
    'domain_enabled' => false,
    'match_filter' => { 'type' => 'match_all' },
    'forwards' => [{ 'type' => 'webhook', 'value' => 'https://example.com' }]
  }
puts ms_inbound_routes.add_inbound_route

More examplesopen in new window

Request Parameters

JSON parameters are provided in dot notation

JSON ParameterTypeRequiredLimitationsDetails
domain_idstringyes
namestringyesMax 191 characters.
domain_enabledbooleanyes
inbound_domainstringyes**Max 191 characters, unique, and must end with the current domain name.
catch_filterobject[]yes**
catch_filter.typestringyesMust be one of the inbound's types: catch_all, catch_recipient.
catch_filter.filtersobject[]yes***Max 5.
catch_filter.filters.*.comparerstringyesMust be one of the comparers: equal, not-equal, contains, not-contains, starts-with, ends-with, not-starts-with, not-ends-with.
catch_filter.filters.*.valuestringyesMax 191 characters.
catch_typestringnoMust be one of the catch types: all, one when the catch filter type is set to catch_recipient.
match_filterobject[]yes
match_filter.typestringyesMust be one of the inbound's types: match_all, match_sender, match_domain, match_header.
match_filter.filtersobject[]yes***Max 5.
match_filter.filters.*.comparerstringyesMust be one of the comparers: equal, not-equal, contains, not-contains, starts-with, ends-with, not-starts-with, not-ends-with.
match_filter.filters.*.valuestringyesMax 191 characters.
match_filter.filters.*.keystringyes****Max 191 characters.
match_typestringnoMust be one of the match types: all, one when the match filter type is set to match_sender, match_domain, or match_header.
forwardsobject[]yesMin 1 and max 5.
forwards.*.typestringyesMust be either email or webhook.
forwards.*.valuestringyesMust be distinct, max 191 characters. If its type is webhook, it must be a valid URL. If its type is email, it must be a valid email address.
* Required if inbound is not enabled.
** Required if inbound is enabled.
*** Required if inbound is enabled and filter type is not match_all.
**** Required if match type is match_header.

Responses

Response KeyTypeDetails
dataobjectInbound object created.

Valid

Response Code: 201 CREATED
Response Headers:
	Content-Type: application/json
{
  "data": {
    "id": "v57gn2j67qlr6z4d",
    "name": "Test name",
    "address": "imxbfnpzn7cbhak9lef5@inbound.mailersend.net",
    "domain": "test.mailersend.com",
    "dns_checked_at": null,
    "enabled": true,
    "filters": [
      {
        "type": "catch_recipient",
        "key": null,
        "comparer": "equal",
        "value": "test"
      },
      {
        "type": "match_all",
        "key": null,
        "comparer": null,
        "value": null
      }
    ],
    "forwards": [
      {
        "type": "webhook",
        "value": "https:\/\/yourapp.com\/hook",
        "secret": "jYhafQeTiZgw0qWclkUA7cbqTG3Zfh2j"
      }
    ],
    "priority": 100,
    "mxValues": {
      "priority": 10,
      "target": "inbound.mailersend.net"
    }
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - Validation errors

Update an inbound route

If you want to update the information of an existing inbound route, use this PUT request:

PUT https://api.mailersend.com/v1/inbound/{inbound_id}

Request body

{
	"domain_id": "7nxe3yjmeq28vp0k",
	"name": "Test update",
	"domain_enabled": true,
	"inbound_domain": "test.mailersend.com",
	"inbound_address": "test@inbound.mailersend.net",
	"inbound_subdomain": "inbound",
	"inbound_priority": 100,
	"match_filter": {
		"type": "match_all"
	},
	"catch_filter": {
		"type": "catch_recipient",
		"filters": [
			{
				"comparer": "equal",
				"value": "test"
			}
		]
	},
	"forwards": [
		{
			"type": "webhook",
			"value": "https://yourapp.com/hook"
		}
	]
}
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Inbound;
use \MailerSend\Helpers\Builder\CatchFilter;
use \MailerSend\Helpers\Builder\MatchFilter;
use \MailerSend\Helpers\Builder\Forward;
use \MailerSend\Common\Constants;

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

$mailersend->inbound->update(
    'inboundId',
    (new Inbound('domainId', 'name', true))
        ->setInboundDomain('inboundDomain')
        ->setCatchFilter(
            (new CatchFilter(Constants::TYPE_CATCH_ALL))
        )
        ->setMatchFilter(new MatchFilter(Constants::TYPE_MATCH_ALL))
        ->addForward(new Forward(Constants::COMPARER_EQUAL, 'value'))
);

More examplesopen in new window

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

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

const inbound = new Inbound()
  .setDomainId('domain_id')
  .setName('inbound test 2')
  .setDomainEnabled(false)
  .setMatchFilter({
    type: InboundFilterType.MATCH_ALL,
  })
  .setForwards([
    {
      type: "webhook",
      value: "https://www.yourdomain.com/hook"
    }
  ]);

mailerSend.email.inbound.update('inbound_id', inbound)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import inbound_routing

route_id = "inbound-route-id"

mailer = inbound_routing.NewInbound()

options = {}

_catch_filter = {
    "type": "catch_recipient",
    "filters": [
        {
            "comparer": "equal",
            "value": "test"
        }
    ]
}

_match_filter = {
    "type": "match_all"
}

_forwards = [
    {
        "type": "webhook",
        "value": "https://www.mailersend.com/hook"
    }
]
mailer.set_name("Example route", options)
mailer.set_domain_enabled(True, options)
mailer.set_inbound_domain("test.mailersend.com", options)
mailer.set_catch_filter(_catch_filter, options)

print(mailer.update_inbound_route(route_id))

More examplesopen in new window

package main

import (
	"context"

	"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.TODO()

	inboundID := "inbound-id"

	updateOptions := &mailersend.UpdateInboundOptions{
		Name:          "Example Route",
		DomainEnabled: *mailersend.Bool(true),
		InboundDomain: "inbound.example.com",
		MatchFilter: &mailersend.MatchFilter{
			Type: "match_all",
		},
		CatchFilter: &mailersend.CatchFilter{
			Type: "catch_recipient",
			Filters: []mailersend.Filter{
				{
					Comparer: "equal",
					Value:    "email",
				},
				{
					Comparer: "equal",
					Value:    "emails",
				},
			},
		},
		Forwards: []mailersend.Forwards{
			{
				Type:  "webhook",
				Value: "https://example.com",
			},
		},
	}

	_, _, _ = ms.Inbound.Update(ctx, inboundID, updateOptions)
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.inboundroutes.Forward;
import com.mailersend.sdk.inboundroutes.InboundRoute;

public void updateInboundRoute() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {

        Forward forward = new Forward();
        forward.type = "webhook";
        forward.value = "https://example-domain.com";
        forward.secret = "asdfgh";
    
        InboundRoute route = ms.inboundRoutes().builder()
            .domainId("domain id")
            .name("Updated route name")
            .domainEnabled(false)
            .matchFilter("match_all")
            .forwards(new Forward[] { forward })
            .updateRoute("inbound route id");

        System.out.println(route.id);
        System.out.println(route.name);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.settings =
  {
    'domain_id' => 'yourdomainid',
    'name' => 'inbound_updated',
    'domain_enabled' => false,
    'match_filter' => { 'type' => 'match_all' },
    'forwards' => [{ 'type' => 'webhook', 'value' => 'https://example.com' }]
  }
puts ms_inbound_routes.update_inbound_route(inbound_id: 'idofroute12412')

More examplesopen in new window

Request Parameters

URL parameterTypeRequiredLimitationsDetails
inbound_idstringyes

JSON parameters are provided in dot notation

JSON ParameterTypeRequiredLimitationsDetails
namestringyesMax 191 characters.
domain_enabledbooleanyes
inbound_domainstringyes**Max 191 characters.
inbound_priorityintyes**Min 0 Max 100. Priority weight is ordered in a descending order, 0 has more importance than 100
catch_filterobject[]yes**
catch_filter.typestringyesMust be one of the inbound's types: catch_all, catch_recipient.
catch_filter.filtersobject[]yes***Max 5.
catch_filter.filters.*.comparerstringyesMust be one of the comparers: equal, not-equal, contains, not-contains, starts-with, ends-with, not-starts-with, not-ends-with.
catch_filter.filters.*.valuestringyesMax 191 characters.
catch_typestringnoMust be one of the catch types: all, one when the catch filter type is set to catch_recipient.
match_filterobject[]yes
match_filter.typestringyesMust be one of the inbound's types: match_all, match_sender, match_domain, match_header.
match_filter.filtersobject[]yes***Max 5.
match_filter.filters.*.comparerstringyesMust be one of the comparers: equal, not-equal, contains, not-contains, starts-with, ends-with, not-starts-with, not-ends-with.
match_filter.filters.*.valuestringyesMax 191 characters.
match_filter.filters.*.keystringyes****Max 191 characters.
match_typestringnoMust be one of the match types: all, one when the match filter type is set to match_sender, match_domain, or match_header.
forwardsobject[]yesMin 1 and max 5.
forwards.*.typestringyesMust be either email or webhook.
forwards.*.valuestringyesMust be distinct, max 191 characters. If its type is webhook, it must be a valid URL. If its type is email, it must be a valid email address.
* Required if inbound is not enabled.
** Required if inbound is enabled.
*** Required if inbound is enabled and filter type is not match_all.
**** Required if match type is match_header.

Responses

Response KeyTypeDetails
dataobjectInbound object created.

Valid

Response Code: 200 OK
Response Headers:
	Content-Type: application/json
{
  "data": {
    "id": "v57gn2j67qlr6z4d",
    "name": "Test update",
    "address": "qi5onrgpw4ujkiqg0p9b@inbound.mailersend.net",
    "domain": "test.mailersend.com",
    "dns_checked_at": null,
    "enabled": true,
    "filters": [
      {
        "type": "catch_recipient",
        "key": null,
        "comparer": "equal",
        "value": "test"
      },
      {
        "type": "match_all",
        "key": null,
        "comparer": null,
        "value": null
      }
    ],
    "forwards": [
      {
        "type": "webhook",
        "value": "https:\/\/yourapp.com\/hook",
        "secret": "jYhafQeTiZgw0qWclkUA7cnqTG3Zfh2j"
      }
    ],
    "mxValues": {
      "priority": 10,
      "target": "inbound.mailersend.net"
    }
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - Validation errors

Delete an inbound route

If you want to delete an inbound route, use this DELETE request:

DELETE https://api.mailersend.com/v1/inbound/{inbound_id}

Request parameters

URL parameterTypeRequiredLimitationsDetails
inbound_idstringyes
use MailerSend\MailerSend;

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

$mailersend->inbound->delete('inboundId');

More examplesopen in new window

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

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

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

More examplesopen in new window

from mailersend import inbound_routing

api_key = "API key here"
route_id = "inbound-route-id"

mailer = inbound_routing.NewInbound(api_key)

print(mailer.delete_inbound_route(route_id))

More examplesopen in new window

package main

import (
	"context"

	"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.TODO()

	inboundID := "inbound-id"

	_, _ = ms.Inbound.Delete(ctx, inboundID)
}

More examplesopen in new window

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

public void deleteInboundRoute() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {

        boolean result = ms.inboundRoutes().deleteRoute("inbound route id");

        System.out.println(result);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.delete_route(inbound_id: 'idofroute12412')

More examplesopen in new window

Responses

Valid

Response Code: 200 OK

Error

Response Code: 404 Not Found
Last Updated: