Shares

Email the month's SEO planning

seo_planner.shares.send

SENDS an email (Amazon SES) with the SEO Planner of a month (month_key YYYY-MM): every action of the month with its type, status, description and sub-actions, plus a status summary; with format pdf the month's PDF is attached too. All recipients go in one email (to up to 20, cc up to 20). sender_id picks the From among the senders this person can use (an item of senders in branding.email_domain.get: the organization's verified domain or, for an Account, its workspace's; none or __system__ = MB Suite); 403 sender_not_allowed otherwise. locale (es, en, pt-BR; default es) is the language of the email: texts, month, action types and statuses. The send is recorded in the share history (seo_planner.shares.list). It reaches real inboxes: confirm the recipients first. Errors: 503 pdf_unavailable when the PDF service is not available (format pdf; nothing is sent, retry later); when SES does not send the email, 429 external_rate_limited, 409 external_rejected (its reason in details.provider_message), 503 external_unavailable (it surely did not reach SES: retry) or 409 external_outcome_unknown (no answer: the email may have gone out; check with the recipients before sending it again), all with details.platform ses. Viewers cannot share (403 role_required). Requires full access to the SEO Planner.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

seo_planner:write

Permission

Edit in the module

MCP tool

seo_planner_shares_sendOn the full surface; on the compact one, mb_execute_operation with id: "seo_planner.shares.send".

Declared cost: up to 520 reads and 1 writes per call (they count against the daily quota). Touches an external platform (ses): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo-planner/shares" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "month_key": "MONTH_KEY",
  "format": "pdf",
  "to": [
    "TO"
  ],
  "subject": "SUBJECT",
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

List the SEO planning emails sent

seo_planner.shares.list

Lists the emails that shared the SEO planning, newest first, paginated by cursor: month, format, recipients (to, cc), subject, personal note, sender, who sent it (sent_by with sent_by_name, the person's current name) and how many actions it carried. With month_key (YYYY-MM), only that month's. Viewers cannot see the history (403 role_required). Requires view access to the SEO Planner.

Scope

seo_planner:read

Permission

View the module

MCP tool

seo_planner_shares_listOn the full surface; on the compact one, mb_execute_operation with id: "seo_planner.shares.list".

Declared cost: up to 202 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo-planner/shares" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/seo-planner/shares" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Preview the SEO planning email

seo_planner.shares.preview

Builds, without sending anything, the HTML of the email that seo_planner.shares.send would send for a month (month_key YYYY-MM) in a format (html by default, or pdf: the email that goes with the PDF, without building the PDF), with the branding of the sender it would use (sender_id), the optional personal note and the locale (es by default, as the send). Returns html, action_count (the planner actions of the month) and effective_action_count (the «Total actions» the email shows, where each sub-action counts as one). Viewers cannot preview (403 role_required). Requires view access to the SEO Planner.

Scope

seo_planner:read

Permission

View the module

MCP tool

seo_planner_shares_previewOn the full surface; on the compact one, mb_execute_operation with id: "seo_planner.shares.preview".

Declared cost: up to 510 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo-planner/shares/preview?month_key=MONTH_KEY" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/seo-planner/shares/preview?month_key=MONTH_KEY" \
  -H "Authorization: Bearer $MB_TEST_KEY"