Propose an IndexNow submission or outreach emails for a person to approve in RankParse.

POSThttps://api.rankparse.com/v1/proposalsFree (the action is billed only when it runs)API key

Stores an action as a pending proposal and returns a review_url to show the user. Nothing runs until a person approves it in the RankParse web app. The body is a JSON object with a kind plus that kind's fields. See Proposals for statuses, idempotency and limits.

Body parameters

kindstringrequired

indexnow_submit or outreach_send. Any other value returns 400 invalid_proposal_input.

site_idstring

A website id from List websites. For IndexNow it is optional and, when given, must be the website that owns the URLs' host (400 site_host_mismatch otherwise). For outreach it is required when creating a campaign, and with campaign_id it must match that campaign's website (400 campaign_site_mismatch). A website of another workspace returns 404 site_not_found.

notestring

Why you are proposing this, in one or two plain sentences. Control and invisible characters are removed, the text is cut to 1000 characters, and the reviewer sees it labelled as the agent's note. It never becomes the proposal's title.

client_request_idstring

1 to 64 characters of A-Z a-z 0-9 _ -. Validated and otherwise ignored, because duplicate detection is automatic.

Kind `indexnow_submit`

urlsarray of stringsrequired

1 to 1000 full http(s) URLs, each at most 2048 characters, no explicit port, all on one host that is one of your RankParse websites. The stored list is de-duplicated and sorted, and its total size is capped at about 1.9 MB.

The host must already have an IndexNow key (IndexNow, POST /v1/indexnow/key), otherwise the call returns 400 indexnow_key_not_found. Whether the key file is actually hosted is checked when the proposal runs.

Kind `outreach_send`

Two shapes. Inline contacts: pass site_id, campaign_name and contacts; RankParse reuses the live Gmail campaign with that name on that website, or creates a draft, adds the contacts and proposes them. Existing campaign: pass campaign_id, optionally with extra contacts to add first; without contacts it proposes the campaign's emails that are waiting for review.

campaign_idstring

A campaign of your workspace (up to 64 characters). Must send through Gmail. Unknown ids return 404 campaign_not_found.

campaign_namestring

1 to 200 characters. Required when campaign_id is omitted.

contactsarray of objects

1 to 100 contacts. Required when campaign_id is omitted. Contacts follow the same rules as Add contacts: one per domain, one per email address, people emailed in an earlier campaign are skipped, 500 per campaign. Unknown keys are rejected.

Show properties

emailstringrequired

A researched, real address. Up to 320 characters.

domainstringrequired

The prospect's domain. Up to 253 characters. Use the punycode (xn--) form for internationalized domains.

subjectstringrequired

Up to 500 characters.

bodystringrequired

Plain text, up to 10,000 characters.

namestring

Contact name, up to 200 characters.

domain_authoritynumber

Optional. Values outside 0 to 100 are stored as unknown.

An agent proposal holds at most 100 emails. The website's Gmail mailbox must be connected and working, or the call returns 400 gmail_not_connected. Unknown top-level fields return 400 invalid_proposal_input.

Response

The status code and status tell you what happened:

HTTP	`status`	Meaning
`202`	`awaiting_approval`	The proposal is pending. Nothing has happened. This is the normal result, and the only new-proposal result for outreach.
`202`	`approved`	Either the same action was already approved and is running (`dedupe_hit: true`, with a `review_url`), or the website's policy approved an IndexNow submission automatically and the run will be retried within the hour (the body then has only `status`, `proposal_id` and `message`). Do not propose it again.
`200`	`executed`	IndexNow only: the policy is Automatic and the submission ran immediately. The body has `proposal_id` and `outcome`. The 1 credit is charged.

statusstring

awaiting_approval, approved or executed.

proposal_idstring

prp_ followed by URL-safe characters. Use it with Get a proposal.

review_urlstring

The link to show the user. For outreach it is the campaign page in RankParse, where each email is approved one by one. For IndexNow it opens the proposal on the website's Today page, or the workspace inbox when the proposal has no website. It contains only ids.

titlestring

Built by RankParse from the stored data (counts and host), never from your text. For example Send 12 outreach emails to 12 domains.

dedupe_hitboolean

true when an identical open proposal already existed and was returned instead of a new one.

messagestring

Plain-text guidance to relay to the user.

outcomeobject

Only with status: "executed".

Show properties

statusstring

succeeded or failed.

resultobject

IndexNow: host, url_count, key_location.

errorCodestring | null

A failure code, or null.

Errors

HTTP	Code	When
400	`invalid_proposal_input`	Body is not a JSON object, `kind` is missing or unsupported, a field has the wrong type or is out of range, an unknown field was sent, or `site_id` is missing when creating a campaign.
400	`kind_not_available`	The kind exists but cannot be proposed yet.
400	`indexnow_invalid_url`, `indexnow_too_many_urls`, `indexnow_host_mismatch`	A URL is invalid or uses a port, there are more than 1000, or they span more than one host.
400	`indexnow_host_not_a_website`	The URLs' host is not one of your RankParse websites.
400	`site_host_mismatch`	`site_id` names a different website than the URLs' host.
400	`indexnow_key_not_found`	The host has no IndexNow key yet.
400	`gmail_not_connected`	The website's mailbox is not connected, or Google stopped accepting it and it needs reconnecting.
400	`sending_provider_unsupported`	The campaign does not send through Gmail.
400	`campaign_site_mismatch`	The campaign belongs to a different website than `site_id`.
400	`no_contacts`	Nothing to propose: no emails are waiting for review, or none of the contacts could be added (the message lists the skip reasons).
401	`invalid_api_key`	Missing, invalid or revoked API key.
403	`approval_inbox_not_enabled`	The approval inbox is not switched on for this account. Do not retry.
403	`action_disabled_by_policy`	The owner turned this action Off for the website. Do not retry.
404	`site_not_found`, `campaign_not_found`	The website (or campaign) is not in this account, or the website is archived.
409	`campaign_not_editable`	The campaign cannot take contacts right now, for example while a launch is running. Retry in a moment.
429	`too_many_pending_proposals`, `daily_proposal_limit_reached`, `rate_limited`	See Limits.

Errors use the shape { "error": "<code>", "code": "<code>", "message": "..." }. See Errors.

MCP tools: propose_indexnow_submit (urls, site_id, note) and propose_outreach_send (site_id, campaign_id, campaign_name, contacts, note).

curl -X POST "https://api.rankparse.com/v1/proposals" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "indexnow_submit",
    "site_id": "site_abc123",
    "urls": ["https://example.com/blog/new-post", "https://example.com/pricing"],
    "note": "Published a new post and changed the pricing page."
  }'

Response

{
  "status": "awaiting_approval",
  "proposal_id": "prp_V1StGXR8_Z5jdHi6B-myT",
  "review_url": "https://rankparse.com/dashboard/sites/site_abc123/today?proposal=prp_V1StGXR8_Z5jdHi6B-myT",
  "title": "Submit 2 URLs on example.com to IndexNow",
  "dedupe_hit": false,
  "message": "Waiting for the user's approval in RankParse: Submit 2 URLs on example.com to IndexNow. Nothing happens until they approve it. Tell the user to review it at the review_url, and check list_proposals later for the outcome."
}

200 executed (Automatic policy)

{
  "status": "executed",
  "proposal_id": "prp_V1StGXR8_Z5jdHi6B-myT",
  "outcome": {
    "status": "succeeded",
    "result": { "host": "example.com", "url_count": 2, "key_location": "https://example.com/4f9c2a7e1b3d4c8aa0e6.txt" },
    "errorCode": null
  }
}

Create a proposal

Body parameters

Kind `indexnow_submit`

Kind `outreach_send`

Response

Errors

Get a proposal

Launch a campaign

IndexNow

Create a proposal

Body parametersCopy Anchor Link

Kind indexnow_submitCopy Anchor Link

Kind outreach_sendCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

RelatedCopy Anchor Link

Get a proposal

Launch a campaign

IndexNow

Body parameters

Kind `indexnow_submit`

Kind `outreach_send`

Response

Errors

Related