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
URL parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | no | ||
page | int | no | ||
limit | int | no | Min: 10 , Max: 100 | Default: 25 |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->inbound->getAll($domainId = 'domainId', $page = 1, $limit = 10);
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));
from mailersend import inbound_routing
api_key = "API key here"
mailer = inbound_routing.NewInbound(api_key)
print(mailer.get_inbound_routes())
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)
}
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();
}
}
require "mailersend-ruby"
ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.get_inbound_routes
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 parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
inbound_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->inbound->find('inboundId');
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));
from mailersend import inbound_routing
api_key = "API key here"
mailer = inbound_routing.NewInbound(api_key)
print(mailer.get_inbound_by_id("inbound-id"))
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)
}
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();
}
}
require "mailersend-ruby"
ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.get_single_route(inbound_id: 'idofroute12412')
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'))
);
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));
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())
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)
}
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();
}
}
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
Request Parameters
JSON parameters are provided in dot notation
JSON Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
domain_id | string | yes | ||
name | string | yes | Max 191 characters. | |
domain_enabled | boolean | yes | ||
inbound_domain | string | yes** | Max 191 characters, unique, and must end with the current domain name. | |
catch_filter | object[] | yes** | ||
catch_filter.type | string | yes | Must be one of the inbound's types: catch_all , catch_recipient , match_all , match_sender , match_domain , match_header . | |
catch_filter.filters | object[] | yes*** | Max 5. | |
catch_filter.filters.*.comparer | string | yes | Must be one of the comparers: equal , not-equal , contains , not-contains , starts-with , ends-with , not-starts-with , not-ends-with . | |
catch_filter.filters.*.value | string | yes | Max 191 characters. | |
match_filter | object[] | yes | ||
match_filter.type | string | yes | Must be one of the inbound's types: catch_all , catch_recipient , match_all , match_sender , match_domain , match_header . | |
match_filter.filters | object[] | yes*** | Max 5. | |
match_filter.filters.*.comparer | string | yes | Must be one of the comparers: equal , not-equal , contains , not-contains , starts-with , ends-with , not-starts-with , not-ends-with . | |
match_filter.filters.*.value | string | yes | Max 191 characters. | |
match_filter.filters.*.key | string | yes**** | Max 191 characters. | |
forwards | object[] | yes | Min 1 and max 5. | |
forwards.*.type | string | yes | Must be either email or webhook . | |
forwards.*.value | string | yes | Must 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.
match_all
.
*** Required if inbound is enabled and filter type is not match_header
.
**** Required if match type is Responses
Response Key | Type | Details |
---|---|---|
data | object | Inbound 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'))
);
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));
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))
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)
}
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();
}
}
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')
Request Parameters
URL parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
inbound_id | string | yes |
JSON parameters are provided in dot notation
JSON Parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
name | string | yes | Max 191 characters. | |
domain_enabled | boolean | yes | ||
inbound_domain | string | yes** | Max 191 characters. | |
inbound_priority | int | yes** | Min 0 Max 100. Priority weight is ordered in a descending order, 0 has more importance than 100 | |
catch_filter | object[] | yes** | ||
catch_filter.type | string | yes | Must be one of the inbound's types: catch_all , catch_recipient , match_all , match_sender , match_domain , match_header . | |
catch_filter.filters | object[] | yes*** | Max 5. | |
catch_filter.filters.*.comparer | string | yes | Must be one of the comparers: equal , not-equal , contains , not-contains , starts-with , ends-with , not-starts-with , not-ends-with . | |
catch_filter.filters.*.value | string | yes | Max 191 characters. | |
match_filter | object[] | yes | ||
match_filter.type | string | yes | Must be one of the inbound's types: catch_all , catch_recipient , match_all , match_sender , match_domain , match_header . | |
match_filter.filters | object[] | yes*** | Max 5. | |
match_filter.filters.*.comparer | string | yes | Must be one of the comparers: equal , not-equal , contains , not-contains , starts-with , ends-with , not-starts-with , not-ends-with . | |
match_filter.filters.*.value | string | yes | Max 191 characters. | |
match_filter.filters.*.key | string | yes**** | Max 191 characters. | |
forwards | object[] | yes | Min 1 and max 5. | |
forwards.*.type | string | yes | Must be either email or webhook . | |
forwards.*.value | string | yes | Must 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.
match_all
.
*** Required if inbound is enabled and filter type is not match_header
.
**** Required if match type is Responses
Response Key | Type | Details |
---|---|---|
data | object | Inbound 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 parameter | Type | Required | Limitations | Details |
---|---|---|---|---|
inbound_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->inbound->delete('inboundId');
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));
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))
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)
}
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();
}
}
require "mailersend-ruby"
ms_inbound_routes = Mailersend::InboundRouting.new
ms_inbound_routes.delete_route(inbound_id: 'idofroute12412')
Responses
Valid
Response Code: 200 OK
Error
Response Code: 404 Not Found