Automatic Inline Seeding API

The Automatic Inline Seeding API helps customers automatically send messages from their campaigns to seed addresses. This document is for customers that are sending with SparkPost.

Returns config details for the authenticated account. Only one seed config with 5 match/exclude rules max is currently supported. One or the other of (match, exclude) may be used, not both. Auth context (from API key) provides customer and subaccount IDs.

Request: Create a seed config with match rule

POST /api/v1/inline-seeds/config

{
  "threshold": 1000,
  "duration": 20,
  "reset": 24,
  "match": [
    "my-*"
  ]
}

Response

{
  "results": {
    "threshold": 1000,
    "duration": 20,
    "reset": 24,
    "match": [
      "my-*"
    ],
    "exclude": []
  }
}

Request: Both Match and Exclude rule not specified

POST /api/v1/inline-seeds/config

{
  "threshold": 1000,
  "duration": 20,
  "reset": 24
}

Response

{
  "errors": [
    {
      "message": "Either match or exclude has to be specified"
    }
  ]
}

Create Seed Config

POST/api/v1/inline-seeds/config

Create seed config for the authenticated account.

Request: Remove redundant rule

PUT /api/v1/inline-seeds/config

{
  "threshold": 1000,
  "duration": 20,
  "reset": 24,
  "match": [
    "my-*"
  ]
}

Response

{
  "results": {
    "threshold": 1000,
    "duration": 20,
    "reset": 24,
    "match": [
      "my-*"
    ],
    "exclude": []
  }
}

Request: Too many matches

PUT /api/v1/inline-seeds/config

{
  "threshold": 1000,
  "duration": 20,
  "reset": 24,
  "match": [
    "fred-*",
    "wilma-*",
    "pebbles-*",
    "barney-*",
    "betty-*",
    "bam-bam-*"
  ]
}

Response

{
  "errors": [
    {
      "message": "Match rule limit exceeded (found 6, max is 5)"
    }
  ]
}

Request: Both match and exclude

PUT /api/v1/inline-seeds/config

{
  "threshold": 1000,
  "duration": 20,
  "reset": 24,
  "match": [
    "fred-*",
    "wilma-*"
  ],
  "exclude": [
    "barney-*",
    "betty-*"
  ]
}

Response

{
  "errors": [
    {
      "message": "Incompatible rule type combination: 'match' and 'exclude' are mutually exclusive."
    }
  ]
}

Update Seed Config

PUT/api/v1/inline-seeds/config

Make updates to config details for the authenticated account. Only one seed config with 5 match/exclude rules max is currently supported. Auth context (from API key) provides customer and subaccount IDs.

Request: Get campaigns for primary account and subaccounts

GET /api/v1/inline-seeds/status

Response

{
  "results": [
    {
      "campaign": "my_campaign",
      "sending_domain": "foo.example.com",
      "count": 1256,
      "threshold": 1256,
      "seed_start": 1620078946682,
      "duration": 30
    },
    {
      "campaign": "second_campaign",
      "sending_domain": "bar.example.com",
      "count": 1337,
      "threshold": 5000,
      "seed_start": null,
      "duration": 30,
      "subaccount_id": 123
    }
  ]
}

List Active Campaigns

GET/api/v1/inline-seeds/status

Returns read-only list of seed-eligible campaigns that have recent activity. Intended use case is informational - checking status via API or UI. Set the X-MSYS-SUBACCOUNT header to get campaigns for a specific subaccount (set the header to 0 to get campaigns for the primary account). Do not set the X-MSYS-SUBACCOUNT header to get campaigns for the primary account and all subaccounts.

Request

GET /api/v1/inline-seeds/status?id=my_campaign&sending_domain=foo.example.com

Response

{
  "results": {
    "campaign": "my_campaign",
    "sending_domain": "foo.example.com",
    "count": 1256,
    "threshold": 1256,
    "seed_start": 1620078946682,
    "duration": 30
  }
}

{
  "results": {
    "campaign": "my_campaign",
    "sending_domain": "foo.example.com",
    "count": 1256,
    "threshold": 1256,
    "seed_start": 1620078946682,
    "duration": 30,
    "subaccount_id": 123
  }
}

{
  "errors": [
    {
      "message": "Resource could not be found"
    }
  ]
}

Check Campaign Status

GET/api/v1/inline-seeds/status?id=my_campaign&sending_domain=foo.example.com

Parameters

id string required

sending_domain string required

Returns read-only campaign metadata. Auth context (from API key) provides customer and subaccount IDs.

Request

GET /api/v1/inline-seeds/options

Response

{
  "results": {
    "enabled": true
  }
}

{
  "results": [
    {
      "enabled": true
    },
    {
      "subaccount_id": 1,
      "enabled": false
    }
  ]
}

Get Options

GET/api/v1/inline-seeds/options

Returns Inline Seeds options.
If no subaccount ID is provided via the X-MSYS-SUBACCOUNT header this will return the primary account and all subaccount options.
If a subaccount ID is provided this will return the subaccount's options.

Attributes

enabled boolean, default is false

Whether Automatic Inline Seeding is enabled or not.

account_enabled boolean, default is false

Whether Automatic Inline Seeding is enabled for all subaccounts (including the primary account). Only returned when false and fetching a specific subaccount's options.

If enabled is false Automatic Inline Seeding is currently paused. If set back to true a campaign will resume from its previous state unless it has reached the 24 hour timeout window and been reset. This will not interrupt a campaign that has already begun seeding.

A user can turn off Automatic Inline Seeding for all subaccounts (including the primary account) by setting the account level option "inline_seeds" to false via the Account API. The Account-level option supercedes the API-level option.

Request

PUT /api/v1/inline-seeds/options

{
  "enabled": false
}

Response

// Empty response body

Update Options

PUT/api/v1/inline-seeds/options

Make updates to options for the authenticated account. If no subaccount ID is provided via the X-MSYS-SUBACCOUNT header this will update the primary account's options.