SendGrid

SendGrid Recipients API

Twilio SendGrid Legacy Marketing Campaigns Contacts: Recipients API

Documentation GitHub OpenAPI

Business capability

Customer Data Management BC-420.10

Operations 15

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /v3/contactdb/recipients Add recipients to the contact database · Add recipients #

Ask an LLM

“Can I add new recipients with custom field data to the legacy contact database?”

“What is the rate limit when adding recipients?”

Tell an agent

Add a new recipient to my legacy contact database.

Create recipients with their custom field values in the contactdb.

PATCH /v3/contactdb/recipients Update one or more recipients · Update Recipient #

Ask an LLM

“How can I change custom field data on existing recipients?”

“Can I update several recipients in the same request?”

Tell an agent

Update the custom fields on these existing recipients.

Patch a batch of recipient records with new details.

DELETE /v3/contactdb/recipients Delete several recipients at once · Delete Recipients #

Ask an LLM

“Can I bulk delete recipients by sending an array of their IDs?”

“What does the request need to remove many recipients in one call?”

Tell an agent destructive · confirm first

Bulk delete a batch of recipients by their IDs.

Remove multiple recipients from my contact database in one request.

GET /v3/contactdb/recipients List legacy contact database recipients · Retrieve recipients #

Ask an LLM

“How do I page through all my legacy Marketing Campaigns recipients?”

“Why might I get an empty page of recipients before reaching the end?”

Tell an agent

List my recipients, page {page} with {page_size} per page.

Show all recipients in my legacy contact database.

GET /v3/contactdb/recipients/{recipient_id} Get a single recipient · Retrieve a single recipient #

Ask an LLM

“What details are stored for one recipient in my contact database?”

“Can I pull up a specific recipient by their ID?”

Tell an agent

Get recipient {recipient_id}.

Show the stored details for recipient ID {recipient_id}.

DELETE /v3/contactdb/recipients/{recipient_id} Permanently delete one recipient · Delete a Recipient #

Ask an LLM

“How do I permanently remove one person from all lists and segments, for example for a privacy request?”

“Does deleting a single recipient also take them off every segment?”

Tell an agent destructive · confirm first

Permanently delete recipient {recipient_id}.

Remove recipient {recipient_id} from all my lists and segments.

GET /v3/contactdb/recipients/{recipient_id}/lists See which lists a recipient belongs to · Retrieve the lists that a recipient is on #

Ask an LLM

“Which lists is a particular recipient on?”

“Can one recipient be on many lists, and how do I see them all?”

Tell an agent

Show the lists that recipient {recipient_id} has been added to.

List every contact list containing recipient {recipient_id}.

GET /v3/contactdb/recipients/billable_count Get the billable recipient count · Retrieve the count of billable recipients #

Ask an LLM

“How many Marketing Campaigns recipients am I being billed for?”

“Is billing based on my highest recipient count at one time?”

Tell an agent

Get my billable recipient count.

Tell me how many recipients count toward my Marketing Campaigns bill.

GET /v3/contactdb/recipients/count Count all recipients · Retrieve a Count of Recipients #

Ask an LLM

“What is the total number of recipients in my legacy contact database?”

“How many recipients do I currently have overall?”

Tell an agent

Count all of my Marketing Campaigns recipients.

Give me the total recipient count.

GET /v3/contactdb/recipients/search Search recipients by a field value · Search recipients #

Ask an LLM

“Can I find recipients by the value of a custom field like first_name or a date field?”

“Which kinds of recipient fields can I search with a simple query string?”

Tell an agent

Find recipients whose field value is {field_name}.

Search recipients where a custom field equals {field_name} using the query-string search.

POST /v3/contactdb/recipients/search Search recipients with segment conditions · Search recipients #

Ask an LLM

“Can I test segment conditions against recipients without creating a segment?”

“Which operators can I use in recipient search conditions?”

Tell an agent

Search list {list_id} for recipients matching conditions {conditions}.

Run segment conditions {conditions} against list {list_id} without saving a segment.

GET /v3/contactdb/status Check recipient upload status · Get Recipient Upload Status #

Ask an LLM

“Are my recipient uploads still processing?”

“Where do I check the upload status for Marketing Campaigns recipients?”

Tell an agent

Check my recipient upload status.

Tell me whether recipient uploads have finished processing.

POST /v3/contactdb/exports Export recipients from lists or segments · Export Recipients #

Ask an LLM

“How do I export recipients from a list or segment to a file?”

“Can I be emailed a link when a recipient export is ready?”

Tell an agent

Export recipients in lists {list_ids} as {file_type}.

Start a recipient export for segments {segment_ids} capped at {max_file_size} MB per file.

GET /v3/contactdb/exports List recipient export jobs · Get All Existing Exports #

Ask an LLM

“Which recipient exports are running or recently completed?”

“Can I see the export type and status of every recipient export job?”

Tell an agent

List all of my recipient export jobs.

Show recipient exports that are in flight or recently done.

GET /v3/contactdb/exports/{id} Check a recipient export's status · Export Recipients Status #

Ask an LLM

“Has my recipient export finished, and where do I download it?”

“What is the current status of one recipient export job?”

Tell an agent

Check the status of recipient export {id}.

Get the download URLs for recipient export {id}.

Documentation

https://www.twilio.com/docs/sendgrid/api-reference/account-provisioning

https://www.twilio.com/docs/sendgrid/api-reference/alerts

https://www.twilio.com/docs/sendgrid/api-reference/api-keys

https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication

https://www.twilio.com/docs/sendgrid/api-reference/email-activity

https://www.twilio.com/docs/sendgrid/api-reference/email-address-validation

https://www.twilio.com/docs/sendgrid/api-reference/enforced-tls

https://www.twilio.com/docs/sendgrid/api-reference/sendgrid-integrations

https://www.twilio.com/docs/sendgrid/api-reference/ip-access-management

https://www.twilio.com/docs/sendgrid/api-reference/ip-address-management-api

https://www.twilio.com/docs/sendgrid/api-reference/ip-warmup

https://www.twilio.com/docs/sendgrid/api-reference/ip-address

https://www.twilio.com/docs/sendgrid/api-reference/link-branding

https://www.twilio.com/docs/sendgrid/api-reference/campaigns-api

https://www.twilio.com/docs/sendgrid/api-reference/contacts-api-custom-fields

https://www.twilio.com/docs/sendgrid/api-reference/sender-identities-api

https://www.twilio.com/docs/sendgrid/api-reference/mail-settings

https://www.twilio.com/docs/sendgrid/api-reference/mail-send

https://www.twilio.com/docs/sendgrid/api-reference/contacts

https://www.twilio.com/docs/sendgrid/api-reference/custom-fields

https://www.twilio.com/docs/sendgrid/api-reference/designs-api

https://www.twilio.com/docs/sendgrid/api-reference/lists

https://www.twilio.com/docs/sendgrid/api-reference/segmenting-contacts-v2

https://www.twilio.com/docs/sendgrid/api-reference/segmenting-contacts

https://www.twilio.com/docs/sendgrid/api-reference/senders

https://www.twilio.com/docs/sendgrid/api-reference/single-sends

https://www.twilio.com/docs/sendgrid/api-reference/marketing-campaign-stats

https://www.twilio.com/docs/sendgrid/api-reference/send-test-email

https://www.twilio.com/docs/sendgrid/api-reference/partner-settings

https://www.twilio.com/docs/sendgrid/api-reference/recipients-data-erasure

https://www.twilio.com/docs/sendgrid/api-reference/reverse-dns

https://www.twilio.com/docs/sendgrid/api-reference/cancel-scheduled-sends

https://www.twilio.com/docs/sendgrid/api-reference/api-key-permissions

https://www.twilio.com/docs/sendgrid/api-reference/sendgrid-engagement-quality-api

https://www.twilio.com/docs/sendgrid/api-reference/single-sign-on-settings

https://www.twilio.com/docs/sendgrid/api-reference/stats

https://www.twilio.com/docs/sendgrid/api-reference/subusers-api

https://www.twilio.com/docs/sendgrid/api-reference/suppressions-unsubscribe-groups

https://www.twilio.com/docs/sendgrid/api-reference/teammates

https://www.twilio.com/docs/sendgrid/api-reference/transactional-templates

https://www.twilio.com/docs/sendgrid/api-reference/settings-tracking

https://www.twilio.com/docs/sendgrid/api-reference/users-api

https://www.twilio.com/docs/sendgrid/api-reference/sender-verification

https://www.twilio.com/docs/sendgrid/api-reference/webhooks

Specifications

https://artifacts.apis.io/sendgrid/openapi/sendgrid-recipients-api-openapi.yml

Schemas & Data

https://artifacts.apis.io/sendgrid/json-schema/sendgrid-contactdb-recipient200-schema.json

https://artifacts.apis.io/sendgrid/json-schema/sendgrid-contactdb-recipient-response201-schema.json

https://artifacts.apis.io/sendgrid/json-schema/sendgrid-recipient-export-schema.json

https://artifacts.apis.io/sendgrid/json-schema/sendgrid-metadata-schema.json

https://artifacts.apis.io/sendgrid/json-schema/sendgrid-contactdb-list2xx-schema.json

https://artifacts.apis.io/sendgrid/json-schema/sendgrid-contactdb-segments-conditions-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/sendgrid:sendgrid-recipients-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Twilio SendGrid Legacy Marketing Campaigns Contacts…
  summary: The Twilio SendGrid Legacy Marketing Campaigns Contacts API allows you to manage your marketing contacts programmatically. SendGrid recommends [moving to the latest version of Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/migrating-from-legacy-marketing-campaigns) if you are using this API.
  description: 'The Twilio SendGrid Legacy Marketing Campaigns Contacts API allows you to manage your marketing contacts programmatically. This API is operational, but we recommend using the current version of Marketing Campaigns'' Contacts API, Lists API, and Segments API to manage your contacts.


    See **Migrating from Legacy Marketing Campaigns** for more information.'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: lmc_contactdb
servers:
- url: https://api.sendgrid.com
  description: The Twilio SendGrid v3 API
security:
- BearerAuth: []
tags:


# --- truncated at 32 KB (48 KB total) ---
# Full source: https://artifacts.apis.io/sendgrid/openapi/sendgrid-recipients-api-openapi.yml