Sendbound API Reference

Canonical request fields, permissions, and MCP coverage generated from the Sendbound API.

This page uses the same generated contract as the OpenAPI download and remote MCP server. Project API keys never grant access to another project's resources. See the inbound guide for receiving setup, webhook payloads, signatures, retries, and attachments.

This reference is generated from the API’s routes and request validators. Download the OpenAPI specification. JSON bodies go directly to the API; MCP tools use a body object and a query object.

Generated request examples contain placeholders. Replace addresses, URLs, resource IDs and other placeholder values before sending. Conditional rules and refinements are enforced by the API at runtime.

GET/contacts

list (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: list_contacts

Parameter	Location	Required	Type
`limit`	query	No	string
`cursor`	query	No	string
`search`	query	No	string
`subscribed`	query	No	string
`sort`	query	No	string
`dir`	query	No	string
`tagId`	query	No	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts

create (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: create_contact

Request body: `application/json`

Field	Required	Type / constraints
`email`	Yes	string, email
`data`	No / conditional	object
`subscribed`	No / conditional	boolean

Complete request JSON Schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "data": {
      "type": "object",
      "additionalProperties": {}
    },
    "subscribed": {
      "type": "boolean"
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/export

export Contacts (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_export_contacts

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/fields

get Available Fields (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_get_available_fields

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/suppressions

list Suppressions (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_list_suppressions

Parameter	Location	Required	Type
`type`	query	No	string
`page`	query	No	string
`pageSize`	query	No	string
`search`	query	No	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/suppressions

add Suppression (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_add_suppression

Request body: `application/json`

Field	Required	Type / constraints
`email`	No / conditional	JSON
`reason`	No / conditional	JSON

Complete request JSON Schema

{
  "type": "object",
  "properties": {
    "email": {},
    "reason": {}
  },
  "additionalProperties": true
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 201, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

DELETE/contacts/suppressions/:contactId

remove Suppression (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_remove_suppression

Parameter	Location	Required	Type
`contactId`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/suppressions/stats

suppression Stats (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_suppression_stats

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/suppressions/export

export Suppressions (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_export_suppressions

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/fields/:field/values

get Field Values (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_get_field_values

Parameter	Location	Required	Type
`field`	path	Yes	string
`limit`	query	No	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/:id

get (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: get_contact

Parameter	Location	Required	Type
`id`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

PATCH/contacts/:id

update (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: update_contact

Parameter	Location	Required	Type
`id`	path	Yes	string

Request body: `application/json`

Field	Required	Type / constraints
`email`	No / conditional	string, email
`data`	No / conditional	object
`subscribed`	No / conditional	boolean

Complete request JSON Schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "data": {
      "type": "object",
      "additionalProperties": {}
    },
    "subscribed": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

DELETE/contacts/:id

delete (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: delete_contact

Parameter	Location	Required	Type
`id`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 204, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/:id/tags

add Tags (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_add_tags

Parameter	Location	Required	Type
`id`	path	Yes	string

Request body: `application/json`

Field	Required	Type / constraints
`tagIds`	No / conditional	JSON

Complete request JSON Schema

{
  "type": "object",
  "properties": {
    "tagIds": {}
  },
  "additionalProperties": true
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

DELETE/contacts/:id/tags/:tagId

remove Tag (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_remove_tag

Parameter	Location	Required	Type
`id`	path	Yes	string
`tagId`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 204, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/:id/emails

get Emails (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_get_emails

Parameter	Location	Required	Type
`id`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/public/:id

get Public (contacts)

Authentication: Public/application-specific authentication; see the flow-specific guide.

MCP: Not exposed through remote MCP; account administration, credentials, browser tracking, and dashboard aliases retain their own authorization.

Parameter	Location	Required	Type
`id`	path	Yes	string

Public/token-authenticated application flow. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/public/:id/subscribe

subscribe Public (contacts)

Authentication: Public/application-specific authentication; see the flow-specific guide.

MCP: Not exposed through remote MCP; account administration, credentials, browser tracking, and dashboard aliases retain their own authorization.

Parameter	Location	Required	Type
`id`	path	Yes	string

Public/token-authenticated application flow. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/public/:id/unsubscribe

unsubscribe Public (contacts)

Authentication: Public/application-specific authentication; see the flow-specific guide.

MCP: Not exposed through remote MCP; account administration, credentials, browser tracking, and dashboard aliases retain their own authorization.

Parameter	Location	Required	Type
`id`	path	Yes	string

Public/token-authenticated application flow. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/lookup

lookup (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_lookup

Request body: `application/json`

Field	Required	Type / constraints
`emails`	No / conditional	JSON

Complete request JSON Schema

{
  "type": "object",
  "properties": {
    "emails": {}
  },
  "additionalProperties": true
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/import

import Csv (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_import_csv

Request body: `multipart/form-data`

Field	Required	Type / constraints
`file`	Yes	string, binary

Complete request JSON Schema

{
  "type": "object",
  "required": [
    "file"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  }
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 202, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/import/:jobId

get Import Status (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_get_import_status

Parameter	Location	Required	Type
`jobId`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/fields/:field/usage

get Field Usage (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_get_field_usage

Parameter	Location	Required	Type
`field`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

DELETE/contacts/fields/:field

delete Field (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_delete_field

Parameter	Location	Required	Type
`field`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/bulk-subscribe

bulk Subscribe (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_bulk_subscribe

Request body: `application/json`

See the complete schema below for union/conditional input, or additional JSON fields. The server applies its runtime validation.

Complete request JSON Schema

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "ids"
          ]
        },
        "contactIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "minItems": 1,
          "maxItems": 1000
        }
      },
      "required": [
        "mode",
        "contactIds"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "query"
          ]
        },
        "filter": {
          "type": "object",
          "properties": {
            "search": {
              "type": "string",
              "maxLength": 255
            },
            "subscribed": {
              "type": "boolean"
            },
            "tagId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "additionalProperties": false,
          "default": {}
        },
        "excludeIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "maxItems": 10000
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": false
    }
  ]
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 202, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/bulk-unsubscribe

bulk Unsubscribe (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_bulk_unsubscribe

Request body: `application/json`

See the complete schema below for union/conditional input, or additional JSON fields. The server applies its runtime validation.

Complete request JSON Schema

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "ids"
          ]
        },
        "contactIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "minItems": 1,
          "maxItems": 1000
        }
      },
      "required": [
        "mode",
        "contactIds"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "query"
          ]
        },
        "filter": {
          "type": "object",
          "properties": {
            "search": {
              "type": "string",
              "maxLength": 255
            },
            "subscribed": {
              "type": "boolean"
            },
            "tagId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "additionalProperties": false,
          "default": {}
        },
        "excludeIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "maxItems": 10000
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": false
    }
  ]
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 202, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

POST/contacts/bulk-delete

bulk Delete (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_bulk_delete

Request body: `application/json`

See the complete schema below for union/conditional input, or additional JSON fields. The server applies its runtime validation.

Complete request JSON Schema

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "ids"
          ]
        },
        "contactIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "minItems": 1,
          "maxItems": 1000
        }
      },
      "required": [
        "mode",
        "contactIds"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "query"
          ]
        },
        "filter": {
          "type": "object",
          "properties": {
            "search": {
              "type": "string",
              "maxLength": 255
            },
            "subscribed": {
              "type": "boolean"
            },
            "tagId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "additionalProperties": false,
          "default": {}
        },
        "excludeIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "maxItems": 10000
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": false
    }
  ]
}

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 202, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

GET/contacts/bulk/:jobId

get Bulk Action Status (contacts)

Authentication: Secret project API key. Resources are scoped to that project.

MCP: contacts_get_bulk_action_status

Parameter	Location	Required	Type
`jobId`	path	Yes	string

Project-scoped customer operation. Server enforces project ownership and additional cross-field validation. IDs are UUIDs, not prefixed placeholders.

Response codes: 200, 400, 401, 403, 404, 429, 500, 503. Errors do not imply that an uncertain send is safe to repeat. A successful sending response confirms API acceptance, not inbox delivery.

Contacts

Request body: application/json

Request body: application/json

Request body: application/json

Request body: application/json

Request body: application/json

Request body: multipart/form-data

Request body: application/json

Request body: application/json

Request body: application/json

Request body: `application/json`

Request body: `application/json`

Request body: `application/json`

Request body: `application/json`

Request body: `application/json`

Request body: `multipart/form-data`

Request body: `application/json`

Request body: `application/json`

Request body: `application/json`