Adds or updates up to 1000 recipients per request. This is the endpoint a signup hook, nightly job or Zapier/n8n flow should call: sending the same payload twice is harmless, and sending a changed one updates the contact in place. See the sync guide for end-to-end recipes.How each entry is matched and what happens:
The entry…
Result
has an external_id that is already on the list
That recipient is updated — including its email, if it changed
has an email that is on the list with no external_id
That recipient is updated and adopts the external_id
matches nothing
Added as a new active recipient
matches a removed recipient
Reactivated, then updated
matches an unsubscribed recipient
Left completely untouched; counted in skipped_unsubscribed. Only the person can opt back in — from the unsubscribe page, or through Resubscribe Recipient when they do it in your app
has an email that belongs to a differentexternal_id
Reported in conflicts, nothing changed
name and external_id are only written when you send them. attributes replaces the stored map when present. Upsert never deletes: remove departed users with Remove Recipient.
Authentication
This endpoint requires an API token passed as a Bearer token in the Authorization header.
Authorization: Bearer YOUR_API_TOKEN
Path Parameters
string
required
The mailing list’s unique identifier (UUID).
Body
(string | object)[]
required
1–1000 entries. A plain string is an email address. An object has:
Show Recipient object
string
required
Email address (case-insensitive)
string
Display name, up to 200 characters. Used for the greeting in release emails.
string
Your own id for this person (user id, customer id), up to 255 characters, unique per list. Key by it so an email change updates the same recipient.
object
Up to 20 keys (≤ 64 chars each) with string, number, boolean or null values; at most 2 KB serialized. Replaces the stored map.
{ "detail": "A list can have at most 500 active recipients on this plan (498 already on this list, 5 to activate)", "code": "recipient_cap_exceeded", "active_count": 498, "limit": 500, "incoming": 5}
Status
Description
400
Applying the batch would exceed the list’s plan cap (max_active_recipients on the list: 500 Free, 2,500 Solo, 10,000 Team). Nothing is written. The body carries code: "recipient_cap_exceeded" plus active_count, limit and incoming, so a sync can detect it and alert rather than retry
401
Invalid or expired API token
404
Mailing list not found in the token’s project
422
Invalid request body (empty array, more than 1000 entries, oversize attributes)
Rate Limits
This endpoint is limited to 30 requests per minute per IP.
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Shipstar","colors":{"primary":"#007A47","light":"#00DC82","dark":"#006B3E"},"logo":{"light":"https://mintcdn.com/shipstar/UUkwwvdaEj90vqzY/logo/light.svg?fit=max\u0026auto=format\u0026n=UUkwwvdaEj90vqzY\u0026q=85\u0026s=923f84c33cd78fd3d3a496de8807d26c","dark":"https://mintcdn.com/shipstar/UUkwwvdaEj90vqzY/logo/dark.svg?fit=max\u0026auto=format\u0026n=UUkwwvdaEj90vqzY\u0026q=85\u0026s=d102097ae3dc99b0e4840e1061e18577"},"favicon":"https://mintcdn.com/shipstar/UUkwwvdaEj90vqzY/favicon.svg?fit=max\u0026auto=format\u0026n=UUkwwvdaEj90vqzY\u0026q=85\u0026s=13a86f14950ba998ce023837c3f01003","api":{},"appearance":{"default":"dark"},"navbar":{"links":[{"href":"https://app.shipstar.ai","label":"Dashboard"}],"primary":{"type":"button","label":"Get API Key","href":"https://app.shipstar.ai/dashboard"}},"footer":{"socials":{"x":"https://twitter.com/shipstarai","github":"https://github.com/shipstar"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"shipstar","hasAudioNarration":false,"actualSubdomain":"shipstar","customDomains":["docs.shipstar.ai"],"gitSource":{"type":"github","owner":"turbo-labs","repo":"shipstar-ai","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{},"buildId":"6af7ea98d68a94726960030c","clientVersion":"0.0.4205","searchFilterCounts":[{"language":"default","tag":"MCP Services","count":39},{"language":"default","tag":"API Reference","count":29},{"language":"default","tag":"Documentation","count":11},{"language":"default","tag":"Mailing Lists","count":10},{"language":"default","tag":"Generation Tools","count":10},{"language":"default","tag":"Project \u0026 Delivery Tools","count":8},{"language":"default","tag":"Get Started","count":7},{"language":"default","tag":"Agent Skills","count":7},{"language":"default","tag":"Guides","count":6},{"language":"default","tag":"Lifecycle Tools","count":5}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/mailing-lists/upsert-recipients","slug":"/api-reference/mailing-lists/upsert-recipients","pageMetadata":{"title":"Upsert Recipients","api":"PUT /email/lists/{list_id}/recipients","description":"Idempotent add-or-update — the call to sync your user base against","href":"/api-reference/mailing-lists/upsert-recipients"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Idempotent add-or-update — the call to sync your user base against\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,CodeGroup,Expandable,Heading,ParamField,ResponseField,Table}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!CodeGroup)_missingMdxReference(`CodeGroup`,true);if(!Expandable)_missingMdxReference(`Expandable`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Adds or updates up to 1000 recipients per request. This is the endpoint a signup hook, nightly job or Zapier/n8n flow should call: sending the same payload twice is harmless, and sending a changed one updates the contact in place. See the `,_jsx(_components.a,{href:`/guides/sync-mailing-list`,children:`sync guide`}),` for end-to-end recipes.`]}),`\n`,_jsx(_components.p,{children:`How each entry is matched and what happens:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`The entry…`}),_jsx(_components.th,{children:`Result`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`has an `,_jsx(_components.code,{children:`external_id`}),` that is already on the list`]}),_jsx(_components.td,{children:`That recipient is updated — including its email, if it changed`})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`has an email that is on the list with no `,_jsx(_components.code,{children:`external_id`})]}),_jsxs(_components.td,{children:[`That recipient is updated and adopts the `,_jsx(_components.code,{children:`external_id`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`matches nothing`}),_jsx(_components.td,{children:`Added as a new active recipient`})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`matches a `,_jsx(_components.code,{children:`removed`}),` recipient`]}),_jsx(_components.td,{children:`Reactivated, then updated`})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`matches an `,_jsx(_components.code,{children:`unsubscribed`}),` recipient`]}),_jsxs(_components.td,{children:[`Left completely untouched; counted in `,_jsx(_components.code,{children:`skipped_unsubscribed`}),`. Only the person can opt back in — from the unsubscribe page, or through `,_jsx(_components.a,{href:`/api-reference/mailing-lists/resubscribe-recipient`,children:`Resubscribe Recipient`}),` when they do it in your app`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`has an email that belongs to a `,_jsx(_components.em,{children:`different`}),` `,_jsx(_components.code,{children:`external_id`})]}),_jsxs(_components.td,{children:[`Reported in `,_jsx(_components.code,{children:`conflicts`}),`, nothing changed`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`name`}),` and `,_jsx(_components.code,{children:`external_id`}),` are only written when you send them. `,_jsx(_components.code,{children:`attributes`}),` replaces the stored map when present. Upsert never deletes: remove departed users with `,_jsx(_components.a,{href:`/api-reference/mailing-lists/remove-recipient`,children:`Remove Recipient`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`authentication`,children:`Authentication`}),`\n`,_jsxs(_components.p,{children:[`This endpoint requires an API token passed as a Bearer token in the `,_jsx(_components.code,{children:`Authorization`}),` header.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`Authorization:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` YOUR_API_TOKEN`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`path-parameters`,children:`Path Parameters`}),`\n`,_jsx(ParamField,{path:`list_id`,type:`string`,required:true,id:`param-list-id`,children:_jsx(_components.p,{children:`The mailing list’s unique identifier (UUID).`})}),`\n`,_jsx(Heading,{level:`2`,id:`body`,children:`Body`}),`\n`,_jsxs(ParamField,{body:`recipients`,type:`(string | object)[]`,required:true,id:`param-recipients`,children:[_jsx(_components.p,{children:`1–1000 entries. A plain string is an email address. An object has:`}),_jsxs(Expandable,{title:`Recipient object`,children:[_jsx(ParamField,{body:`email`,type:`string`,required:true,id:`param-email`,children:`Email address (case-insensitive)`}),_jsx(ParamField,{body:`name`,type:`string`,id:`param-name`,children:`Display name, up to 200 characters. Used for the greeting in release emails.`}),_jsx(ParamField,{body:`external_id`,type:`string`,id:`param-external-id`,children:`Your own id for this person (user id, customer id), up to 255 characters, unique per list. Key by it so an email change updates the same recipient.`}),_jsx(ParamField,{body:`attributes`,type:`object`,id:`param-attributes`,children:`Up to 20 keys (≤ 64 chars each) with string, number, boolean or null values; at most 2 KB serialized. Replaces the stored map.`})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`request`,children:`Request`}),`\n`,_jsxs(CodeGroup,{children:[_jsx(CodeBlock,{filename:`cURL`,numberOfLines:`9`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`9`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` PUT`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"https://api.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890/recipients\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer YOUR_API_TOKEN\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"recipients\": [`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` {\"email\": \"sam@example.com\", \"name\": \"Sam Lee\", \"external_id\": \"usr_42\", \"attributes\": {\"plan\": \"pro\"}},`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"casey@example.com\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),_jsx(CodeBlock,{filename:`JavaScript`,numberOfLines:`16`,language:`javascript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`javascript`,children:_jsxs(_components.code,{language:`javascript`,numberOfLines:`16`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` listId`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` response`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` fetch`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"`https://api.shipstar.ai/api/v1/email/lists/\"}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:\"${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`listId`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"/recipients`\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` method:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'PUT'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` headers:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Authorization'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Bearer YOUR_API_TOKEN'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Content-Type'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'application/json'`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` body:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` JSON`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`stringify`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` recipients:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`email:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'sam@example.com'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`name:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'Sam Lee'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`external_id:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'usr_42'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`attributes:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`plan:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'pro'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` } },`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'casey@example.com'`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` })`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` result`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` response`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`json`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`();`})]}),`\n`]})})}),_jsx(CodeBlock,{filename:`Python`,numberOfLines:`14`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`14`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requests`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`list_id `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`response `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requests.put(`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'https://api.shipstar.ai/api/v1/email/lists/`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`{`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`list_id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`}`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`/recipients'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` headers`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'Authorization'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'Bearer YOUR_API_TOKEN'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#9CDCFE`},children:` json`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'recipients'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'email'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'sam@example.com'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'name'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'Sam Lee'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'external_id'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'usr_42'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'attributes'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'plan'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'pro'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'casey@example.com'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]},`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`result `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.json()`})]}),`\n`]})})})]}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsx(ResponseField,{name:`added`,type:`integer`,required:true,id:`param-added`,children:`New recipients created`}),`\n`,_jsx(ResponseField,{name:`updated`,type:`integer`,required:true,id:`param-updated`,children:`Existing active recipients whose fields changed`}),`\n`,_jsx(ResponseField,{name:`reactivated`,type:`integer`,required:true,id:`param-reactivated`,children:`Removed recipients put back on the list`}),`\n`,_jsx(ResponseField,{name:`unchanged`,type:`integer`,required:true,id:`param-unchanged`,children:`Entries that matched an active recipient with identical fields`}),`\n`,_jsx(ResponseField,{name:`skipped_unsubscribed`,type:`integer`,required:true,id:`param-skipped-unsubscribed`,children:`Entries that matched a recipient who unsubscribed; nothing was changed`}),`\n`,_jsx(ResponseField,{name:`invalid`,type:`string[]`,required:true,id:`param-invalid`,children:`Entries whose email failed validation`}),`\n`,_jsx(ResponseField,{name:`conflicts`,type:`object[]`,required:true,id:`param-conflicts`,children:_jsxs(_components.p,{children:[`Entries that could not be applied, each with `,_jsx(_components.code,{children:`email`}),`, `,_jsx(_components.code,{children:`external_id`}),` and a `,_jsx(_components.code,{children:`reason`}),`.`]})}),`\n`,_jsx(CodeBlock,{filename:`200`,numberOfLines:`9`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`9`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"added\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"updated\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"reactivated\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"unchanged\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"skipped_unsubscribed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"invalid\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"conflicts\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: []`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`errors`,children:`Errors`}),`\n`,_jsx(CodeBlock,{filename:`400`,numberOfLines:`7`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`7`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"detail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"A list can have at most 500 active recipients on this plan (498 already on this list, 5 to activate)\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"code\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"recipient_cap_exceeded\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"active_count\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`498`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"limit\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`500`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"incoming\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`5`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`400`}),_jsxs(_components.td,{children:[`Applying the batch would exceed the list’s plan cap (`,_jsx(_components.code,{children:`max_active_recipients`}),` on the list: 500 Free, 2,500 Solo, 10,000 Team). Nothing is written. The body carries `,_jsx(_components.code,{children:`code: \"recipient_cap_exceeded\"`}),` plus `,_jsx(_components.code,{children:`active_count`}),`, `,_jsx(_components.code,{children:`limit`}),` and `,_jsx(_components.code,{children:`incoming`}),`, so a sync can detect it and alert rather than retry`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`401`}),_jsx(_components.td,{children:`Invalid or expired API token`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`404`}),_jsx(_components.td,{children:`Mailing list not found in the token’s project`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:`422`}),_jsx(_components.td,{children:`Invalid request body (empty array, more than 1000 entries, oversize attributes)`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`rate-limits`,children:`Rate Limits`}),`\n`,_jsx(_components.p,{children:`This endpoint is limited to 30 requests per minute per IP.`})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Upsert Recipients","api":"PUT /email/lists/{list_id}/recipients","description":"Idempotent add-or-update — the call to sync your user base against","href":"/api-reference/mailing-lists/upsert-recipients"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Authentication","slug":"authentication","depth":2,"children":[]},{"title":"Path Parameters","slug":"path-parameters","depth":2,"children":[]},{"title":"Body","slug":"body","depth":2,"children":[]},{"title":"Request","slug":"request","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"Errors","slug":"errors","depth":2,"children":[]},{"title":"Rate Limits","slug":"rate-limits","depth":2,"children":[]}],"codeExamples":{},"endpoint":{"title":"Upsert Recipients","path":"/email/lists/{list_id}/recipients","method":"put","request":{"security":[],"parameters":{"query":{},"header":{},"cookie":{},"path":{"list_id":{"schema":[{"type":"string","description":"The mailing list’s unique identifier (UUID).","required":true}]}}},"body":{"application/json":{"schemaArray":[{"type":"object","properties":{"recipients":[{"type":"array","items":[{"type":"object","properties":{"email":[{"type":"string","description":"Email address (case-insensitive)","required":true}],"name":[{"type":"string","description":"Display name, up to 200 characters. Used for the greeting in release emails."}],"external_id":[{"type":"string","description":"Your own id for this person (user id, customer id), up to 255 characters, unique per list. Key by it so an email change updates the same recipient."}],"attributes":[{"type":"object","properties":{},"description":"Up to 20 keys (≤ 64 chars each) with string, number, boolean or null values; at most 2 KB serialized. Replaces the stored map."}]}}],"description":"1–1000 entries. A plain string is an email address. An object has:","required":true}]}}],"examples":{"example":{"value":{"recipients":[{"email":"\u003cstring>","name":"\u003cstring>","external_id":"\u003cstring>","attributes":{}}]}}}}}},"response":{"200":{"application/json":{"schemaArray":[{"type":"object","properties":{"added":[{"type":"integer","description":"New recipients created","required":true}],"updated":[{"type":"integer","description":"Existing active recipients whose fields changed","required":true}],"reactivated":[{"type":"integer","description":"Removed recipients put back on the list","required":true}],"unchanged":[{"type":"integer","description":"Entries that matched an active recipient with identical fields","required":true}],"skipped_unsubscribed":[{"type":"integer","description":"Entries that matched a recipient who unsubscribed; nothing was changed","required":true}],"invalid":[{"type":"array","items":[{"type":"string"}],"description":"Entries whose email failed validation","required":true}],"conflicts":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"Entries that could not be applied, each with `email` , `external_id` and a `reason` .","required":true}]}}],"examples":{"example":{"value":{"added":123,"updated":123,"reactivated":123,"unchanged":123,"skipped_unsubscribed":123,"invalid":["\u003cstring>"],"conflicts":[{}]}}}}}},"deprecated":false}},"jsLinks":[],"subdomain":"shipstar","siteName":"Shipstar","title":"Upsert Recipients - Shipstar","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-09T18:52:14.429Z","originalFileLocation":"api-reference/mailing-lists/upsert-recipients.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Idempotent add-or-update — the call to sync your user base against\">\u003cmeta data-mint-head name=\"application-name\" content=\"Shipstar\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Upsert Recipients - Shipstar\">\u003cmeta data-mint-head property=\"og:description\" content=\"Idempotent add-or-update — the call to sync your user base against\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Shipstar\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://shipstar.mintlify.site/_mintlify/api/og/v2?division=Mailing+Lists\u0026amp;title=Upsert+Recipients\u0026amp;description=Idempotent+add-or-update+%E2%80%94+the+call+to+sync+your+user+base+against\u0026amp;theme=db1c0867b3dbc92d03394e47\u0026amp;signature=6c08b22ed3426abf6a125c3ac34d3c24409d1239d2d229cce6d0c4d19534c644\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Upsert Recipients - Shipstar\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Idempotent add-or-update — the call to sync your user base against\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://shipstar.mintlify.site/_mintlify/api/og/v2?division=Mailing+Lists\u0026amp;title=Upsert+Recipients\u0026amp;description=Idempotent+add-or-update+%E2%80%94+the+call+to+sync+your+user+base+against\u0026amp;theme=db1c0867b3dbc92d03394e47\u0026amp;signature=6c08b22ed3426abf6a125c3ac34d3c24409d1239d2d229cce6d0c4d19534c644\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/shipstar/sv7TW8CmKuFRAxza/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Shipstar\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#007A47\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/mailing-lists/upsert-recipients.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.shipstar.ai/#organization\",\"name\":\"Shipstar\",\"url\":\"https://docs.shipstar.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/shipstar/UUkwwvdaEj90vqzY/logo/light.svg?fit=max\u0026auto=format\u0026n=UUkwwvdaEj90vqzY\u0026q=85\u0026s=923f84c33cd78fd3d3a496de8807d26c\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.shipstar.ai#website\",\"name\":\"Shipstar\",\"url\":\"https://docs.shipstar.ai\",\"publisher\":{\"@id\":\"https://docs.shipstar.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients#webpage\",\"url\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients\",\"name\":\"Upsert Recipients\",\"description\":\"Idempotent add-or-update — the call to sync your user base against\",\"dateModified\":\"2026-11-09T18:52:14.429Z\",\"isPartOf\":{\"@id\":\"https://docs.shipstar.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Mailing Lists\",\"item\":\"https://docs.shipstar.ai/api-reference/mailing-lists/list-mailing-lists\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Upsert Recipients\",\"item\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients#apireference\",\"headline\":\"Upsert Recipients\",\"name\":\"Upsert Recipients\",\"description\":\"Idempotent add-or-update — the call to sync your user base against\",\"url\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients\",\"mainEntityOfPage\":{\"@id\":\"https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients#webpage\"},\"dateModified\":\"2026-11-09T18:52:14.429Z\",\"publisher\":{\"@id\":\"https://docs.shipstar.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.shipstar.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Shipstar\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Shipstar\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/mailing-lists/upsert-recipients.md","siteName":"Shipstar","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"MCP Services","pages":[{"title":"MCP Services","href":"/mcp/overview"}]},{"tab":"API Reference","groups":[{"group":"API Reference","pages":[{"title":"Shipstar API Overview","href":"/api-reference/overview"},{"title":"Health Check","api":"GET /health","href":"/api-reference/health"},{"title":"Get Current User","api":"GET /me","href":"/api-reference/authentication"},{"title":"Shipstar API Versioning \u0026 Deprecation Policy","href":"/api-reference/versioning"}]},{"group":"Changelog","pages":[{"title":"List Published Changelogs","api":"GET /changelogs","href":"/api-reference/changelog/list-changelogs"},{"title":"Get Public Changelog","api":"GET /changelog/{public_slug}","href":"/api-reference/changelog/get-changelog"},{"title":"Get Changelog RSS Feed","api":"GET /changelog/{public_slug}/feed","href":"/api-reference/changelog/changelog-feed"}]},{"group":"Blog","pages":[{"title":"List Published Blog Posts","api":"GET /blogs","href":"/api-reference/blog/list-blog-posts"},{"title":"Get Public Blog Post","api":"GET /blog/{public_slug}","href":"/api-reference/blog/get-blog-post"},{"title":"Get Blog Post RSS Feed","api":"GET /blog/{public_slug}/feed","href":"/api-reference/blog/blog-post-feed"},{"title":"Get All Blogs RSS Feed","api":"GET /blogs/feed","href":"/api-reference/blog/all-blogs-feed"}]},{"group":"Knowledge Base","pages":[{"title":"List Published KB Articles","api":"GET /kb","href":"/api-reference/kb/list-kb-articles"},{"title":"Get Public KB Articles","api":"GET /kb/{public_slug}","href":"/api-reference/kb/get-kb-articles"}]},{"group":"Banner","pages":[{"title":"Get Live Banner","api":"GET /banner","href":"/api-reference/banner/get-live-banner"},{"title":"Get Banner by Slug","api":"GET /banner/{public_slug}","href":"/api-reference/banner/get-banner"}]},{"group":"Mailing Lists","pages":[{"title":"List Mailing Lists","api":"GET /email/lists","href":"/api-reference/mailing-lists/list-mailing-lists"},{"title":"Create Mailing List","api":"POST /email/lists","href":"/api-reference/mailing-lists/create-mailing-list"},{"title":"Get Mailing List","api":"GET /email/lists/{list_id}","href":"/api-reference/mailing-lists/get-mailing-list"},{"title":"List Recipients","api":"GET /email/lists/{list_id}/recipients","description":"Page through a mailing list's recipients, with status filter and search","href":"/api-reference/mailing-lists/list-recipients"},{"title":"Upsert Recipients","api":"PUT /email/lists/{list_id}/recipients","href":"/api-reference/mailing-lists/upsert-recipients"},{"title":"Add Recipients","api":"POST /email/lists/{list_id}/recipients","description":"Bulk-add email addresses to a mailing list","href":"/api-reference/mailing-lists/add-recipients"},{"title":"Remove Recipients","api":"DELETE /email/lists/{list_id}/recipients/{identifier}","href":"/api-reference/mailing-lists/remove-recipient"},{"title":"Resubscribe Recipient","api":"POST /email/lists/{list_id}/recipients/resubscribe","href":"/api-reference/mailing-lists/resubscribe-recipient"},{"title":"Erase Recipients","api":"POST /email/lists/{list_id}/recipients/erase","href":"/api-reference/mailing-lists/erase-recipients"},{"title":"Export Recipients","api":"GET /email/lists/{list_id}/recipients/export.csv","href":"/api-reference/mailing-lists/export-recipients"}]}]}]},"basePath":"","title":"Upsert Recipients - Shipstar","deploymentId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","buildId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-B6WFFOBL.js","utils-BN5um1KA.js","cloneDeep-C3md22mN.js","_Uint8Array-DLlL8L26.js","isObject-FP1Yky1u.js","utils-BSmbkXJR.js","addUniqueKeysToSchema-2tqcVnUE.js","snippetPresets-CtWfvr2J.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DkKHBy30.js","isEqual-O3q7y6pq.js","usePlaygroundInputsStore-Brc5H9UJ.js","shallow-C4L4xvbs.js","getApiPlaygroundDisplay-2bxyq_aI.js","CodeSnippet-BJu8ddd5.js","CodeSnippets-dazWmoqB.js","Page-CnLhKuUV.js","getPastedJson-Chy3Qa1S.js","icon-CyO7h3jh.js","MethodPill-Dle0_91v.js","DuplicateIcon-CVvWAf4a.js","createIcon-Di07A27B.js","DynamicMarkdown-C4w9kavL.js","SectionHeading-XiBebVYC.js","axios-vUo_bRtp.js"]}