--- name: "newsletters_invite" area: "newsletters" title: "Invite people to a newsletter" price: "free" method: "POST" url: "https://api.conecto.chat/v1/tools/newsletters_invite" mcp_server: "https://api.conecto.chat/mcp/newsletters" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/newsletters/newsletters_invite" --- # Invite people to a newsletter (`newsletters_invite`) Emails each person a request to confirm a subscription; only those who confirm ever get an issue. Email each person a request to confirm their subscription: only those who press Confirm ever get an issue. For people who asked to hear from the business. Skips anyone already in, invited in the last day, unsubscribed or undeliverable. At most 20 invitations a day per account. Free: they go out through the business's own email service. Price: Free. A call that fails costs nothing. ## Use it when People asked to hear from the business, in person or by email, and should be signed up. ## Say this to your agent > Rachel Kim and Marcus Webb asked about new arrivals in the shop. Invite them to Halverson Ride Notes. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `newsletter` | string | yes | The newsletter's slug (from newsletters_list) or its exact name. 1 to 120 characters. | | | | `people` | array of objects | yes | 1 to 50 items. | | | | `people[].email` | string | yes, in each item of `people` | Up to 254 characters. | | | | `people[].name` | string | no | Up to 120 characters. | | | | `how_they_asked` | string | yes | How these people asked to hear from the business, like "they signed up at the counter" or "they asked for it by email". The invitations are checked first: people who never asked are cold outreach, and nobody is invited. 3 to 300 characters. | | | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `newsletters_invite` on the MCP server `https://api.conecto.chat/mcp/newsletters` with these arguments: ```json { "newsletter": "halverson-ride-notes", "people": [ { "email": "rachel.kim@example.com", "name": "Rachel Kim" }, { "email": "marcus.webb@example.com", "name": "Marcus Webb" } ], "how_they_asked": "They asked about new arrivals at the shop counter." } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/newsletters_invite \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"newsletter": "halverson-ride-notes", "people": [{"email": "rachel.kim@example.com", "name": "Rachel Kim"}, {"email": "marcus.webb@example.com", "name": "Marcus Webb"}], "how_they_asked": "They asked about new arrivals at the shop counter."}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "newsletters_invite", "status": "succeeded", "replayed": false, "cost_usd": "$0.00", "balance_usd": "$19.75", "result": { "invited": [ "rachel.kim@example.com", "marcus.webb@example.com" ], "skipped": [], "invitations_left_today": 18 } } ``` `result`: invited: the people sent an invitation, skipped: the ones left out with the reason (already in, invited lately, unsubscribed, undeliverable), and invitations_left_today. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No newsletter of the business has that slug or name. | Call newsletters_list and use a slug from it. | | `no_sending_service` | 409 | The business has not connected its own email service. | Connect it with newsletters_connect_service (its SMTP server, login and from address). | | `invalid_input` | 400 | An address is not an email address. | Fix or drop the address the message names. | | `cold_email` | 422 | The invitations look like cold outreach, to people who never asked to hear from the business. | Invite only people who asked, and say how they did in how_they_asked. | | `check_unavailable` | 503 | The check invitations go through couldn't run just now. | Try again in a minute. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [newsletters_connect_service](https://conecto.chat/tools/newsletters/newsletters_connect_service.md): Connects the business's own email service (Brevo, Amazon SES, Mailgun or any SMTP server), which every newsletter email goes out through. Free. - [newsletters_remove_service](https://conecto.chat/tools/newsletters/newsletters_remove_service.md): Disconnects the business's email service and forgets its password; newsletters wait until one is connected again. Free. - [newsletters_create](https://conecto.chat/tools/newsletters/newsletters_create.md): Creates a newsletter people join on its own page by confirming their address, sent through the business's own email service. Free. - [newsletters_update](https://conecto.chat/tools/newsletters/newsletters_update.md): Renames a newsletter or changes its description, postal address or archive. Free. - [newsletters_list](https://conecto.chat/tools/newsletters/newsletters_list.md): The business's newsletters with their pages and subscriber counts, and the email service they go out through. Free up to 1,000,000 reads a month. - [newsletters_subscribers](https://conecto.chat/tools/newsletters/newsletters_subscribers.md): Who is on a newsletter, newest first: confirmed, waiting to confirm, unsubscribed, bounced or complained. Free up to 1,000,000 reads a month. - [newsletters_remove_subscriber](https://conecto.chat/tools/newsletters/newsletters_remove_subscriber.md): Deletes someone from a newsletter for good, with their history. Free. - [newsletters_write_issue](https://conecto.chat/tools/newsletters/newsletters_write_issue.md): Writes a draft issue in Markdown, to test and then send. Free. - [newsletters_update_issue](https://conecto.chat/tools/newsletters/newsletters_update_issue.md): Changes a draft issue's subject, body or preheader. Free. - [newsletters_send_test](https://conecto.chat/tools/newsletters/newsletters_send_test.md): Emails an issue to up to 5 addresses as subscribers will see it, marked [Test]. Free. - [newsletters_send_issue](https://conecto.chat/tools/newsletters/newsletters_send_issue.md): Sends a draft to everyone who confirmed, now or at a set time, through the business's own email service. Free. - [newsletters_cancel_issue](https://conecto.chat/tools/newsletters/newsletters_cancel_issue.md): Stops a scheduled issue, or one still going out; what went out already stays sent. Free. - [newsletters_get_issue](https://conecto.chat/tools/newsletters/newsletters_get_issue.md): One issue: its text, where it stands, and once sent how many it reached, bounced, unsubscribed and clicked, link by link. Free up to 1,000,000 reads a month. - [newsletters_list_issues](https://conecto.chat/tools/newsletters/newsletters_list_issues.md): A newsletter's issues, newest first, optionally of one status. Free up to 1,000,000 reads a month.