POST /contacts/{id}/segments/{segmentId}

Request

The same call in curl, Node and Python. A path id in the sample is a placeholder.

curl

curl -sS -X POST https://api.agentisend.com/contacts/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42/segments/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42 \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Node

import { AgentiSend } from 'agentisend';

const client = new AgentiSend(process.env.AGENTISEND_API_KEY);
const result = await client.request({
  method: 'POST',
  path: '/contacts/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42/segments/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42',
});

Python

import json, os, urllib.request

url = 'https://api.agentisend.com/contacts/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42/segments/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42'
headers = {'Authorization': 'Bearer ' + os.environ['AGENTISEND_API_KEY']}
request = urllib.request.Request(url, headers=headers, method='POST')
print(urllib.request.urlopen(request).read().decode())

Tag: contacts. Generated from openapi.json; the anchor post-contacts-id-segments-segmentid is the id the console's error fix links point at.

Parameters

• id path · string · required
• segmentId path · string · required
• Idempotency-Key header · string · optional — Makes this call safe to retry. Send the same key with the same body and the original response is replayed instead of the work happening twice. Keys are 1-256 characters and are remembered for 7 days. While the first attempt is still running, a second call with that key returns 409 idempotency_in_flight (Resend calls this concurrent_idempotent_requests); the same key with a different body returns 409 idempotency_payload_mismatch (Resend: invalid_idempotent_request). Resend-Idempotency-Key is accepted as the same header.
• Resend-Idempotency-Key header · string · optional — Alias of Idempotency-Key. Idempotency-Key wins if both are sent.

Responses

• 201 — Success
• 400 — The request is malformed or a field failed validation. Codes: validation_error, invalid_idempotency_key, invalid_cursor, plan_not_purchasable, stripe_signature_invalid, support_upload_rejected, sign_in_check_required.
• 409 — The request conflicts with the current state. Codes: domain_already_exists, template_name_taken, template_in_use, segment_in_use, contact_resubscribe_required, domain_verified_elsewhere, return_path_subdomain_in_use, overage_not_on_plan, term_not_on_sale, subscription_active, already_in_account, idempotency_in_flight, idempotency_payload_mismatch, approval_expired, support_closed, support_reopen_expired, support_merge_conflict.
• 413 — The request body is larger than this operation accepts. Codes: payload_too_large, support_upload_too_large.
• 415 — The request body is not JSON. Codes: unsupported_media_type.
• 429 — A rate, quota or ramp ceiling was reached. Codes: onboarding_daily_cap_reached, trust_throttled, invite_limit_reached, rate_ceiling_exceeded, daily_quota_exceeded, monthly_quota_exceeded, rate_limit_exceeded, support_rate_limited.
• 500 — Something failed on our side. Codes: internal_server_error.

Response headers

• ratelimit-limit — Messages this API key may spend in one 60-second window.
• ratelimit-remaining — Messages left in the current window.
• ratelimit-reset — Seconds until the current window resets and the budget refills.

Errors

The codes this operation can answer with, and what to do about each. Every one arrives with its code, message, fix and docs_url.

• idempotency_in_flight (409) — A request with this Idempotency-Key is still in progress. Fix: Wait and retry with the same Idempotency-Key to receive the original response.
• idempotency_payload_mismatch (409) — Same Idempotency-Key was used with a different payload. Fix: Reuse the exact same body for retries, or send a new Idempotency-Key for a new request.
• internal_server_error (500, internal_server_error) — Unexpected error. Fix: Retry ONCE after a short pause, with the same Idempotency-Key so the retry cannot double-send. If it fails again, stop retrying and report the x-request-id from the response — that id is what identifies this exact failure in support.
• invalid_idempotency_key (400) — Idempotency-Key must be 1-256 characters. Fix: Send a non-empty Idempotency-Key header of at most 256 characters.
• payload_too_large (413) — Request body is larger than this endpoint accepts. Fix: Send a smaller body. Most endpoints accept 1 MB. Sends (POST /emails, /emails/batch, replies) and template, broadcast and automation edits accept 50 MB, which fits 40 MB of attachments after base64. /mcp accepts 1 MB per JSON-RPC call.
• rate_limit_exceeded (429, rate_ceiling_exceeded, rate_limit_exceeded) — Too many requests. Fix: Back off and retry honoring the Retry-After header.
• unsupported_media_type (415) — This endpoint does not accept that content type. Fix: Send the body as JSON with `Content-Type: application/json`.
• validation_error (400, domain_not_verified, invalid_parameter, validation_error) — Error in one or more fields. Fix: Correct the fields listed in the error details and retry the request.