Shares

Email a media plan

media_planner.shares.send

SENDS an email (Amazon SES) with a media plan: its window, budget by currency and by platform and, in campaigns mode, the campaign table; with format pdf the plan's PDF is attached too. One email to everyone (to and cc, up to 50 recipients in total), with an optional personal_note and the subject given. 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 its agency's; none or __system__ = MB Suite), and the email carries that sender's branding; 403 sender_not_allowed otherwise. locale (es, en, pt-BR) for the email and the PDF. The send is recorded in the plan's share history (media_planner.shares.list) and fires media_planner.plan.shared. It reaches real inboxes: outside the app it needs a dry run (it says the recipients, the From, the subject and the format, with the same sender check) and its confirm_token; media_planner.shares.preview gives the HTML. Errors: 503 pdf_unavailable when the PDF service is not available (nothing was sent: retry, or send format html); when Amazon SES does not send it, 429 external_rate_limited, 409 external_rejected, 503 external_unavailable (it surely did not go out) or 409 external_outcome_unknown (SES did not answer: the email may have gone out, check before sending it again). Requires full access to the Media Planner. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

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

media_planner:write

Permission

Edit in the module

MCP tool

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

Events it can emit

media_planner.plan.shared

Declared cost: up to 503 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/media-planner/plans/{plan_id}/shares" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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.

Preview a media plan email

media_planner.shares.preview

Builds, without sending anything, the HTML of the email media_planner.shares.send would send for a plan, with the branding of the sender it would use (sender_id), the personal note and the locale (default: the person's language). The PDF is not generated. Returns html: the whole email, often 50,000 to 100,000 characters (a big plan, more); ask for it only to show or check the email itself (media_planner.plans.get has the plan's data). Requires access to the Media Planner and a role other than viewer (403 role_required). Through the API and the MCP it depends on the terms of LinkedIn: where they do not allow it, it answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Scope

media_planner:read

Permission

View the module

MCP tool

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

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/shares/preview" \
  -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/media-planner/plans/{plan_id}/shares/preview" \
  -H "Authorization: Bearer $MB_TEST_KEY"

List the emails sent with a media plan

media_planner.shares.list

Lists the emails sent with a media plan, newest first, paginated by cursor: format, recipients (to, cc), subject, personal note, sender and who sent it, and whether a PDF (has_pdf) and an HTML copy (has_html) are stored (12 months). Get them with media_planner.shares.pdf_url and media_planner.shares.html. Requires access to the Media Planner and a role other than viewer (viewers do not see who received the plan: 403 role_required).

Scope

media_planner:read

Permission

View the module

MCP tool

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

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/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/media-planner/plans/{plan_id}/shares" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get a download link for the PDF of a sent email

media_planner.shares.pdf_url

Returns a signed download link for the PDF stored with a sent email of the plan (valid 1 hour for an API key or an app; 7 days in the app) and when it expires. 409 share_pdf_unavailable if that email had no PDF (html format, or sent before February 21, 2026) and share_pdf_expired if it is older than 12 months. Anyone with the link can download the file until it expires: do not post it in public places. Requires access to the Media Planner and a role other than viewer. Through the API and the MCP it depends on the terms of LinkedIn: where they do not allow it, it answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Scope

media_planner:read

Permission

View the module

MCP tool

media_planner_shares_pdf_urlOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.shares.pdf_url".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/shares/{share_id}/pdf-url" \
  -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/media-planner/plans/{plan_id}/shares/{share_id}/pdf-url" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get the HTML of a sent email

media_planner.shares.html

Returns the HTML of an email exactly as it was sent with the plan (the copy stored for 12 months): the whole email, often 50,000 to 100,000 characters; ask for it only to show or check the email itself (media_planner.shares.list has who got it and when). 409 share_html_unavailable for emails sent before February 21, 2026, and share_html_expired after 12 months. Requires access to the Media Planner and a role other than viewer. Through the API and the MCP it depends on the terms of LinkedIn: where they do not allow it, it answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

Scope

media_planner:read

Permission

View the module

MCP tool

media_planner_shares_htmlOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.shares.html".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/shares/{share_id}/html" \
  -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/media-planner/plans/{plan_id}/shares/{share_id}/html" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete the record of a sent email

media_planner.shares.delete

Deletes the record of an email sent with the plan and its stored PDF and HTML copies. The email itself was already delivered and is not recalled. It does not go to the trash. Only owners and admins. Outside the app it needs a dry run and a confirm_token. Requires full access to the Media 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

media_planner:write and “Allow deletions” (media_planner:delete in OAuth)

Permission

Edit in the module · Only owner, admin

MCP tool

media_planner_shares_deleteOn the full surface; on the compact one, mb_execute_operation with id: "media_planner.shares.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/shares/{share_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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.

curl -X DELETE "https://api.mb-suite.com/v1/media-planner/plans/{plan_id}/shares/{share_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'