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

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-1.api.bird.com/api

/workspaces/{workspaceId}/reach/relay-webhooks

Returns a list of all your relay webhooks.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Responses

200

Successfully retrieved relay webhooks list

application/json

get

/workspaces/{workspaceId}/reach/relay-webhooks

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/relay-webhooks HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Successfully retrieved relay webhooks list

{
  "results": [
    {
      "id": "text",
      "name": "text",
      "target": "text",
      "auth_token": "text",
      "auth_type": "text",
      "auth_request_details": {},
      "custom_headers": {},
      "match": {
        "protocol": "text",
        "domain": "text"
      }
    }
  ]
}

Create a Relay Webhook

post

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-1.api.bird.com/api

/workspaces/{workspaceId}/reach/relay-webhooks

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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Body

application/json

namestringOptional

Relay webhook name

targetstringRequired

URL of the target to which to POST relay batches. Only ports 80 for http and 443 for https can be set.

auth_typestring · enumOptional

Type of authentication to be used during POST requests to target

Default: nonePossible values:

auth_tokenstringOptional

Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target

custom_headersobjectOptional

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

Relay webhook created successfully

application/json

400

Request validation error

application/json

409

Domain is already in use

application/json

422

Unprocessable entity

application/json

post

/workspaces/{workspaceId}/reach/relay-webhooks

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/relay-webhooks HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "name": "text",
  "target": "text",
  "auth_type": "none",
  "auth_request_details": {
    "url": "text",
    "body": {}
  },
  "auth_token": "text",
  "match": {
    "protocol": "SMTP",
    "domain": "text"
  },
  "custom_headers": {}
}

{
  "results": {
    "id": "text"
  }
}

Retrieve a Relay Webhook

get

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-1.api.bird.com/api

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

relayWebhookIdstringRequired

The ID of the relay webhook

Responses

200

Successfully retrieved relay webhook

application/json

404

Resource could not be found

application/json

get

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}

HTTPcURLJavaScriptPython

GET /api/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "results": {
    "name": "text",
    "target": "text",
    "auth_token": "text",
    "auth_type": "text",
    "auth_request_details": {},
    "custom_headers": {},
    "match": {
      "protocol": "text",
      "domain": "text"
    }
  }
}

Update a Relay Webhook

put

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-1.api.bird.com/api

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

relayWebhookIdstringRequired

The ID of the relay webhook

Body

application/json

namestringOptional

Relay webhook name

targetstringOptional

URL of the target to which to POST relay batches. Only ports 80 for http and 443 for https can be set.

auth_typestring · enumOptional

Type of authentication to be used during POST requests to target

Possible values:

auth_request_detailsobjectOptional

Object containing details needed to request authorization token for OAuth 2.0. Required when auth_type is oauth2.

auth_tokenstringOptional

Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target

custom_headersobjectOptional

Object of custom HTTP headers to be used during POST requests to target

Responses

200

Relay webhook updated successfully

application/json

400

Request validation error

application/json

404

Resource could not be found

application/json

409

Domain is already in use

application/json

put

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}

HTTPcURLJavaScriptPython

PUT /api/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "name": "text",
  "target": "text",
  "auth_type": "none",
  "auth_request_details": {},
  "auth_token": "text",
  "match": {
    "protocol": "SMTP",
    "domain": "text"
  },
  "custom_headers": {}
}

{
  "results": {
    "id": "text"
  }
}

Delete a Relay Webhook

delete

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-1.api.bird.com/api

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

relayWebhookIdstringRequired

The ID of the relay webhook

Responses

200

Relay webhook deleted successfully

No content

404

Resource could not be found

application/json

delete

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}

HTTPcURLJavaScriptPython

DELETE /api/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId} HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

No content

Validate a Relay Webhook

post

https://email.eu-west-1.api.bird.com/apihttps://email.us-west-1.api.bird.com/api

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}/validate

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.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

relayWebhookIdstringRequired

The ID of the relay webhook

Responses

200

Relay webhook validation successful

application/json

post

/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}/validate

HTTPcURLJavaScriptPython

POST /api/workspaces/{workspaceId}/reach/relay-webhooks/{relayWebhookId}/validate HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*

200

Relay webhook validation successful

{
  "results": {
    "msg": "text",
    "response": {
      "status": 1,
      "headers": {},
      "body": "text"
    }
  }
}