Relay Webhooks

Run in Postman
Import the SparkPost API as a Postman collection

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.

Relay Webhook Object

Example

{
  "id": "12013026328707075",
  "name": "Inbound Customer Replies",
  "target": "https://webhooks.customer.example/replies",
  "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
  "match": {
    "protocol": "SMTP",
    "domain": "example.com"
  }
}

Attributes

id string

Unique ID

name string

Relay webhook name

target string

URL of the target to which to POST relay batches

auth_token string

Authentication token to present in the X-MessageSystems-Webhook-Token header of POST requests to target. Use this token in your target application to confirm that data is coming from SparkPost.

match object

Restrict which inbound messages will be relayed to the target.

custom_headers object

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

Custom HTTP Headers Properties

The custom headers JSON object allows you to add up to five 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, and SparkPost may also disallow some HTTP headers for security reasons.

Adding Custom Headers

When creating (POST) or updating (PUT) a Relay Webhook:

{
  "custom_headers": {
    "header1": "value1",
    "header2": "value2"
  }
}

Removing Custom Headers

When updating (PUT) a Relay Webhook:

{
  "custom_headers": {}
}

Relay Webhook Payload

The following fields will be included in each object posted to the relay webhook's target:

Example

[
  {
    "msys": {
      "relay_message": {
        "content": {
          "email_rfc822": "Return-Path: <me@here.com>\r\nMIME-Version: 1.0\r\nFrom: me@here.com\r\nReceived: by 10.114.82.10 with HTTP; Mon, 4 Jul 2016 07:53:14 -0700 (PDT)\r\nDate: Mon, 4 Jul 2016 15:53:14 +0100\r\nMessage-ID: <484810298443-112311-xqxbby@mail.there.com>\r\nSubject: Relay webhooks rawk!\r\nTo: you@there.com\r\nContent-Type: multipart/alternative; boundary=deaddeaffeedf00fall45dbhail980dhypnot0ad\r\n\r\n--deaddeaffeedf00fall45dbhail980dhypnot0ad\r\nContent-Type: text/plain; charset=UTF-8\r\nHi there SparkPostians.\r\n\r\n--deaddeaffeedf00fall45dbhail980dhypnot0ad\r\nContent-Type: text/html; charset=UTF-8\r\n\r\n<p>Hi there <strong>SparkPostians</strong></p>\r\n\r\n--deaddeaffeedf00fall45dbhail980dhypnot0ad--\r\n",
          "email_rfc822_is_base64": false,
          "headers": [
            {
              "Return-Path": "<me@here.com>"
            },
            {
              "MIME-Version": "1.0"
            },
            {
              "From": "me@here.com"
            },
            {
              "Received": "by 10.114.82.10 with HTTP; Mon, 4 Jul 2016 07:53:14 -0700 (PDT)"
            },
            {
              "Date": "Mon, 4 Jul 2016 15:53:14 +0100"
            },
            {
              "Message-ID": "<484810298443-112311-xqxbby@mail.there.com>"
            },
            {
              "Subject": "Relay webhooks rawk!"
            },
            {
              "To": "you@there.com"
            }
          ],
          "html": "<p>Hi there <strong>SparkPostians</strong>.</p>",
          "subject": "We come in peace",
          "text": "Hi there SparkPostians.",
          "to": [
            "your@yourdomain.com"
          ]
        },
        "customer_id": "1337",
        "friendly_from": "me@here.com",
        "msg_from": "me@here.com",
        "rcpt_to": "you@there.com",
        "webhook_id": "4839201967643219"
      }
    }
  }
]

relay_message

content object

The content parsed from the incoming message.

friendly_from string

Email address used to compose the "From" header

msg_from string

SMTP envelope "MAIL FROM", matches "Return-Path" header address

rcpt_to string

SMTP envelope "RCPT TO"

webhook_id string

ID of the relay webhook which triggered this relay message.

protocol string, value is smtp

Protocol of the originating inbound message.

customer_id string

Customer ID of the customer that created the relay webhook.

Request

POST /api/v1/relay-webhooks
{
  "name": "Replies Webhook",
  "target": "https://webhooks.customer.example/replies",
  "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
  "match": {
    "domain": "email.example.com"
  }
}

Response

{
  "results": {
    "id": "12013026328707075"
  }
}
{
  "errors": [
    {
      "message": "invalid params",
      "description": "Domain '(domain)' is not a registered inbound domain",
      "code": "1200"
    }
  ]
}
{
  "errors": [
    {
      "message": "resource conflict",
      "description": "Domain '(domain)' is already in use",
      "code": "1602"
    }
  ]
}
{
  "errors": [
    {
      "message": "Invalid custom header",
      "description": "Header '(header_name)' is reserved and cannot be used",
      "code": "10000"
    }
  ]
}
{
  "errors": [
    {
      "message": "custom_headers exceeded maximum headers allowed",
      "description": "A maximum of 5 custom headers are permitted",
      "code": "10002"
    }
  ]
}

Create a Relay Webhook

POST/api/v1/relay-webhooks

Create a relay webhook by providing a relay webhooks object as the POST request body.

Request Body

name string

Relay webhook name

target string required

URL of the target to which to POST relay batches

auth_token string

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

match object required

Restrict which inbound messages will be relayed to the target.

custom_headers object

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

Request

GET /api/v1/relay-webhooks/12013026328707075

Response

{
  "results": {
    "name": "Replies Webhook",
    "target": "https://webhooks.customer.example/replies",
    "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
    "match": {
      "protocol": "SMTP",
      "domain": "email.example.com"
    }
  }
}
{
  "errors": [
    {
      "message": "Unauthorized Tenant",
      "code": "1303"
    }
  ]
}
{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600"
    }
  ]
}

Retrieve a Relay Webhook

GET/api/v1/relay-webhooks/{id}

Parameters

id string required

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

Request

PUT /api/v1/relay-webhooks/12013026328707075
{
  "name": "New Replies Webhook",
  "target": "https://webhook.customer.example/replies",
  "auth_token": "A different auth token",
  "match": {
    "domain": "email.a-different-domain.com"
  }
}

Response

{
  "results": {
    "id": "12013026328707075"
  }
}
{
  "errors": [
    {
      "message": "invalid params",
      "description": "Domain ('domain') is not a registered inbound domain",
      "code": "1200"
    }
  ]
}
{
  "errors": [
    {
      "message": "invalid params",
      "description": "esme address not configured",
      "code": "1200"
    }
  ]
}
{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600"
    }
  ]
}
{
  "errors": [
    {
      "message": "resource conflict",
      "description": "Domain '(domain)' is already in use",
      "code": "1602"
    }
  ]
}

Update a Relay Webhook

PUT/api/v1/relay-webhooks/{id}

Parameters

id string required

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

Request Body

name string

Relay webhook name

target string

URL of the target to which to POST relay batches

auth_token string

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

match object

Restrict which inbound messages will be relayed to the target.

custom_headers object

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

Request

DELETE /api/v1/relay-webhooks/12013026328707075

Response

// Empty response body
{
  "errors": [
    {
      "message": "resource not found",
      "code": "1600"
    }
  ]
}

Delete a Relay Webhook

DELETE/api/v1/relay-webhooks/{id}

Parameters

id string required

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

Request

GET /api/v1/relay-webhooks

Response

{
  "results": [
    {
      "id": "12013026328707075",
      "name": "Replies Webhook",
      "target": "https://webhooks.customer.example/replies",
      "auth_token": "5ebe2294ecd0e0f08eab7690d2a6ee69",
      "match": {
        "protocol": "SMTP",
        "domain": "email.example.com"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "Unauthorized Tenant",
      "code": "1303"
    }
  ]
}

List all Relay Webhooks

GET/api/v1/relay-webhooks

List all your relay webhooks.