# Relay Webhooks

Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.

#### Custom HTTP Headers

You can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.

#### Match Object

The `match` object restricts which inbound messages will be relayed to the target:

* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)
* `domain`: The inbound domain associated with the relay webhook

### Regional Endpoints

Please use the appropriate API endpoint based on your workspace region:

* EU workspaces: <https://email.eu-west-1.api.bird.com>
* US workspaces: <https://email.us-west-1.api.bird.com>

## List all Relay Webhooks

> Returns a list of all your relay webhooks.

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Relay Webhooks","description":"Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.\n\n### Custom HTTP Headers\n\nYou can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.\n\n### Match Object\n\nThe `match` object restricts which inbound messages will be relayed to the target:\n* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)\n* `domain`: The inbound domain associated with the relay webhook\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/relay-webhooks":{"get":{"tags":["Relay Webhooks"],"summary":"List all Relay Webhooks","description":"Returns a list of all your relay webhooks.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved relay webhooks list","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"target":{"type":"string"},"auth_token":{"type":"string"},"auth_type":{"type":"string"},"auth_request_details":{"type":"object"},"custom_headers":{"type":"object"},"match":{"type":"object","properties":{"protocol":{"type":"string"},"domain":{"type":"string"}}}}}}}}}}}}}}}}
```

## Create a Relay Webhook

> Create a relay webhook by providing a relay webhooks object as the POST request body. Before creating a relay webhook, first create and configure an inbound domain.<br>

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Relay Webhooks","description":"Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.\n\n### Custom HTTP Headers\n\nYou can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.\n\n### Match Object\n\nThe `match` object restricts which inbound messages will be relayed to the target:\n* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)\n* `domain`: The inbound domain associated with the relay webhook\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/relay-webhooks":{"post":{"tags":["Relay Webhooks"],"summary":"Create a Relay Webhook","description":"Create a relay webhook by providing a relay webhooks object as the POST request body. Before creating a relay webhook, first create and configure an inbound domain.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["target","match"],"properties":{"name":{"type":"string","description":"Relay webhook name"},"target":{"type":"string","description":"URL of the target to which to POST relay batches. Only ports 80 for http and 443 for https can be set."},"auth_type":{"type":"string","enum":["none","oauth2"],"default":"none","description":"Type of authentication to be used during POST requests to target"},"auth_request_details":{"type":"object","description":"Object containing details needed to request authorization token for OAuth 2.0. Required when auth_type is oauth2. Only grant_type of credentials is supported.","properties":{"url":{"type":"string","description":"The URL for the authorization server"},"body":{"type":"object","description":"The body to send in the request to the authorization server"}}},"auth_token":{"type":"string","description":"Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target"},"match":{"type":"object","description":"Restrict which inbound messages will be relayed to the target","required":["domain"],"properties":{"protocol":{"type":"string","enum":["SMTP"],"default":"SMTP","description":"The inbound messaging protocol"},"domain":{"type":"string","description":"The inbound domain associated with the relay webhook"}}},"custom_headers":{"type":"object","description":"Object of custom HTTP headers to be used during POST requests to target. Maximum of 5 custom headers, up to 3,000 bytes."}}}}}},"responses":{"200":{"description":"Relay webhook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Domain is already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Retrieve a Relay Webhook

> Retrieve a specific relay webhook by specifying the webhook ID in the URI path.

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Relay Webhooks","description":"Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.\n\n### Custom HTTP Headers\n\nYou can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.\n\n### Match Object\n\nThe `match` object restricts which inbound messages will be relayed to the target:\n* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)\n* `domain`: The inbound domain associated with the relay webhook\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}":{"get":{"tags":["Relay Webhooks"],"summary":"Retrieve a Relay Webhook","description":"Retrieve a specific relay webhook by specifying the webhook ID in the URI path.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"relayWebhookId","in":"path","description":"The ID of the relay webhook","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved relay webhook","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"name":{"type":"string"},"target":{"type":"string"},"auth_token":{"type":"string"},"auth_type":{"type":"string"},"auth_request_details":{"type":"object"},"custom_headers":{"type":"object"},"match":{"type":"object","properties":{"protocol":{"type":"string"},"domain":{"type":"string"}}}}}}}}}},"404":{"description":"Resource could not be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Update a Relay Webhook

> Update a relay webhook by specifying the webhook ID in the URI path.

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Relay Webhooks","description":"Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.\n\n### Custom HTTP Headers\n\nYou can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.\n\n### Match Object\n\nThe `match` object restricts which inbound messages will be relayed to the target:\n* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)\n* `domain`: The inbound domain associated with the relay webhook\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}":{"put":{"tags":["Relay Webhooks"],"summary":"Update a Relay Webhook","description":"Update a relay webhook by specifying the webhook ID in the URI path.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"relayWebhookId","in":"path","description":"The ID of the relay webhook","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Relay webhook name"},"target":{"type":"string","description":"URL of the target to which to POST relay batches. Only ports 80 for http and 443 for https can be set."},"auth_type":{"type":"string","enum":["none","oauth2"],"description":"Type of authentication to be used during POST requests to target"},"auth_request_details":{"type":"object","description":"Object containing details needed to request authorization token for OAuth 2.0. Required when auth_type is oauth2."},"auth_token":{"type":"string","description":"Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target"},"match":{"type":"object","description":"Restrict which inbound messages will be relayed to the target","properties":{"protocol":{"type":"string","enum":["SMTP"],"description":"The inbound messaging protocol"},"domain":{"type":"string","description":"The inbound domain associated with the relay webhook"}}},"custom_headers":{"type":"object","description":"Object of custom HTTP headers to be used during POST requests to target"}}}}}},"responses":{"200":{"description":"Relay webhook updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"id":{"type":"string"}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource could not be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Domain is already in use","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Delete a Relay Webhook

> Delete a specific relay webhook by specifying the webhook ID in the URI path.

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Relay Webhooks","description":"Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.\n\n### Custom HTTP Headers\n\nYou can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.\n\n### Match Object\n\nThe `match` object restricts which inbound messages will be relayed to the target:\n* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)\n* `domain`: The inbound domain associated with the relay webhook\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}":{"delete":{"tags":["Relay Webhooks"],"summary":"Delete a Relay Webhook","description":"Delete a specific relay webhook by specifying the webhook ID in the URI path.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"relayWebhookId","in":"path","description":"The ID of the relay webhook","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Relay webhook deleted successfully"},"404":{"description":"Resource could not be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Validate a Relay Webhook

> The validation request sends an example batch to the target URL, validates that the target responds with HTTP 200, and returns information on the response received from the target.<br>

```json
{"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Relay Webhooks","description":"Relay Webhooks are a way to instruct SparkPost to forward messages sent to an inbound domain to a target URL for your own consumption. Before you create a relay webhook, first create and configure an inbound domain. The Relay Webhooks API provides the means to create, list, retrieve, update, and delete a relay webhook.\n\n### Custom HTTP Headers\n\nYou can add up to 5 custom headers to your relay webhook. The `custom_headers` object may only be up to 3,000 bytes in size, and must be formatted as an object with keys as strings or numbers. Headers already used by SparkPost will not be allowed.\n\n### Match Object\n\nThe `match` object restricts which inbound messages will be relayed to the target:\n* `protocol`: The inbound messaging protocol (currently only `SMTP` is supported)\n* `domain`: The inbound domain associated with the relay webhook\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey <token>` or `Bearer <token>`.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}/validate":{"post":{"tags":["Relay Webhooks"],"summary":"Validate a Relay Webhook","description":"The validation request sends an example batch to the target URL, validates that the target responds with HTTP 200, and returns information on the response received from the target.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"relayWebhookId","in":"path","description":"The ID of the relay webhook","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Relay webhook validation successful","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"msg":{"type":"string"},"response":{"type":"object","properties":{"status":{"type":"integer"},"headers":{"type":"object"},"body":{"type":"string"}}}}}}}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/email-api/relay-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.