Test an inbound route

Sends a synthetic inbound email through the same delivery path as production (outbound webhooks for webhook routes, signed HTTP to the agent for agent routes). Use dryRun: true to preview the payload without delivering.

POST /v1/domains/{domain}/routes/{address}/test

TypeScript

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.domains.routes.test({
    from: {
      address: "58851 Konopelski Overpass",
    },
    subject: "<value>",
  }, "exalted-bonfire.com", "90499 Rowan Close");

  console.log(result);
}

run();

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");

var res = await sdk.Domains.Routes.TestAsync(
    domain: "exalted-bonfire.com",
    address: "90499 Rowan Close",
    testDomainRouteDto: new TestDomainRouteDto() {
        From = new TestDomainRouteFromDto() {
            Address = "58851 Konopelski Overpass",
        },
        Subject = "<value>",
    }
);

// handle response

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity(
        'YOUR_SECRET_KEY_HERE'
    )
    ->build();

$testDomainRouteDto = new Components\TestDomainRouteDto(
    from: new Components\TestDomainRouteFromDto(
        address: '58851 Konopelski Overpass',
    ),
    subject: '<value>',
);

$response = $sdk->domains->routes->test(
    domain: 'exalted-bonfire.com',
    address: '90499 Rowan Close',
    testDomainRouteDto: $testDomainRouteDto

);

if ($response->testDomainRouteResponseDto !== null) {
    // handle response
}

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.domains.routes.test(domain="exalted-bonfire.com", address="90499 Rowan Close", test_domain_route_dto={
        "from_": {
            "address": "58851 Konopelski Overpass",
        },
        "subject": "<value>",
    })

    # Handle response
    print(res)

package main

import(
	"context"
	"github.com/novuhq/novu-go/v3"
	"github.com/novuhq/novu-go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := v3.New(
        v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
    )

    res, err := s.Domains.Routes.Test(ctx, "exalted-bonfire.com", "90499 Rowan Close", components.TestDomainRouteDto{
        From: components.TestDomainRouteFromDto{
            Address: "58851 Konopelski Overpass",
        },
        Subject: "<value>",
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.TestDomainRouteResponseDto != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.novu.co/v1/domains/{domain}/routes/{address}/test \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "address": "<string>",
    "name": "<string>"
  },
  "subject": "<string>",
  "text": "<string>",
  "html": "<string>",
  "dryRun": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: {address: '<string>', name: '<string>'},
    subject: '<string>',
    text: '<string>',
    html: '<string>',
    dryRun: true
  })
};

fetch('https://api.novu.co/v1/domains/{domain}/routes/{address}/test', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/domains/{domain}/routes/{address}/test")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {\n    \"address\": \"<string>\",\n    \"name\": \"<string>\"\n  },\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"dryRun\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/domains/{domain}/routes/{address}/test")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": {\n    \"address\": \"<string>\",\n    \"name\": \"<string>\"\n  },\n  \"subject\": \"<string>\",\n  \"text\": \"<string>\",\n  \"html\": \"<string>\",\n  \"dryRun\": true\n}"

response = http.request(request)
puts response.read_body

200

{
  "matched": true,
  "dryRun": true,
  "mxRecordConfigured": true,
  "wouldDeliverTo": "<string>",
  "payload": {},
  "webhook": {
    "latencyMs": 123,
    "skipped": true
  },
  "agent": {
    "agentId": "<string>",
    "httpStatus": 123,
    "latencyMs": 123,
    "agentReply": {}
  }
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Authorizations

Authorization · string · header · required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

idempotency-key · string

A header for idempotency purposes

Path Parameters

domain · string · required

address · string · required

Body

application/json

from · object · required

Show child attributes

subject · string · required

text · string

html · string

dryRun · boolean

When true, returns the payload that would be delivered without invoking outbound webhooks or the agent HTTP endpoint.

Response

200

application/json

OK

matched · boolean · required

dryRun · boolean · required

domainStatus · enum<string>

Available options: pending, verified

mxRecordConfigured · boolean

type · enum<string>

Available options: agent, webhook

wouldDeliverTo · string

Human-readable delivery target summary in dry-run mode.

payload · object

The outbound payload (dry-run only).

webhook · object

Show child attributes

agent · object

Show child attributes