Update to Twilio Developer Kit

{
  "name": "twilio-email-send",
  "description": "Use when the caller has Twilio credentials (Account SID + Auth Token or API Key SID + Secret) and needs to send email via comms.twilio.com/v1/Emails. This is Twilio-native email — NOT SendGrid. Do NOT use if the caller has a SendGrid API key (SG.-prefix) — use twilio-sendgrid-email-send instead. Covers single sends, batch sends up to 10,000 recipients, Liquid personalization, operation tracking, and error handling.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 215
    }
  ],
  "skill_md_contents": "---\nname: twilio-email-send\ndescription: >\n  Use when the caller has Twilio credentials (Account SID + Auth Token or\n  API Key SID + Secret) and needs to send email via comms.twilio.com/v1/Emails.\n  This is Twilio-native email — NOT SendGrid. Do NOT use if the caller has a\n  SendGrid API key (SG.-prefix) — use twilio-sendgrid-email-send instead.\n  Covers single sends, batch sends up to 10,000 recipients, Liquid\n  personalization, operation tracking, and error handling.\n---\n\n## Overview\n\n> **Agent safety:** Always confirm recipients, subject, and content with the user before sending. Email is irreversible once delivered. Never send email autonomously without explicit user approval — especially for batch sends to multiple recipients.\n\n**Twilio Email is a separate product from SendGrid.** Both send email, but they use different APIs, credentials, templating languages, and endpoints. If you have a SendGrid API key (`SG.`-prefix), use `twilio-sendgrid-email-send` instead.\n\n| | Twilio Email (this skill) | SendGrid |\n|---|---|---|\n| **Base URL** | `https://comms.twilio.com/v1/emails` | `https://api.sendgrid.com/v3/mail/send` |\n| **Auth** | Twilio Account SID + Auth Token (or API Key SID + Secret) | SendGrid API key (`SG.`-prefix) |\n| **Templating** | Liquid (`{{variable}}`) | Handlebars (`{{variable}}`) |\n| **Max recipients/request** | 10,000 | 1,000 |\n| **Max message size** | 10MB (including attachments) | 30MB |\n| **Status tracking** | Operation resource (poll `operationLocation`) | Event Webhooks (async POST) |\n| **Console** | console.twilio.com | app.sendgrid.com |\n\n---\n\n## Prerequisites\n\n- A Twilio account — see `twilio-account-setup` for signup and credentials\n- A **Verified Sender**: an approved domain identity configured in the Twilio console that must match the `from` address domain\n- Compliance with regional anti-spam regulations (CAN-SPAM, GDPR)\n\nFor a complete setup guide, see the Email Onboarding guide in the Twilio console.\n\n---\n\n## Authentication\n\nThe API uses **Basic Authentication** with either:\n- Account SID + Auth Token\n- API Key SID + API Key Secret\n\nThese are standard Twilio credentials — the same ones used for SMS, Voice, and other Twilio APIs.\n\n---\n\n## Send a Simple Email\n\n`POST https://comms.twilio.com/v1/Emails`\n\nThe endpoint is **asynchronous** — it returns `202 Accepted` with an `operationId`, not a delivery confirmation.\n\n```bash\ncurl -X POST \"https://comms.twilio.com/v1/Emails\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"from\": {\n      \"address\": \"support@example.com\",\n      \"name\": \"Support Team\"\n    },\n    \"to\": [\n      {\n        \"address\": \"john.doe@example.com\",\n        \"name\": \"John Doe\"\n      }\n    ],\n    \"content\": {\n      \"subject\": \"Your subject line\",\n      \"html\": \"<p>Your message content in HTML format.</p>\",\n      \"text\": \"Your message content in plain text.\"\n    }\n  }' \\\n  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN\n```\n\nResponse (`202 Accepted`):\n```json\n{\n  \"operationId\": \"...\",\n  \"operationLocation\": \"https://comms.twilio.com/v1/Emails/Operations/...\"\n}\n```\n\nPoll `operationLocation` to track delivery status.\n\n---\n\n## Batch Sending\n\nSend the same message to multiple recipients in a single request by adding entries to the `to` array. Maximum **10,000 recipients** per request.\n\n```json\n{\n  \"from\": {\n    \"address\": \"support@example.com\",\n    \"name\": \"Support Team\"\n  },\n  \"to\": [\n    {\n      \"address\": \"john.doe@example.com\",\n      \"name\": \"John Doe\"\n    },\n    {\n      \"address\": \"jane.smith@example.com\",\n      \"name\": \"Jane Smith\"\n    }\n  ],\n  \"content\": {\n    \"subject\": \"Your subject line\",\n    \"html\": \"<p>Your message content in HTML format.</p>\",\n    \"text\": \"Your message content in plain text.\"\n  }\n}\n```\n\n---\n\n## Liquid Personalization\n\nUse Liquid templating in the `content.subject`, `content.html`, and `content.text` fields. For each variable referenced (e.g. `{{firstName}}`), provide a matching key in the `variables` object for every recipient in the `to` array.\n\n```json\n{\n  \"from\": {\n    \"address\": \"noreply@example.com\",\n    \"name\": \"Support Team\"\n  },\n  \"to\": [\n    {\n      \"address\": \"alice@example.com\",\n      \"name\": \"Alice\",\n      \"variables\": {\"firstName\": \"Alice\", \"orderId\": \"123\"}\n    },\n    {\n      \"address\": \"bob@example.com\",\n      \"name\": \"Bob\",\n      \"variables\": {\"firstName\": \"Bob\", \"orderId\": \"456\"}\n    }\n  ],\n  \"content\": {\n    \"subject\": \"Hi {{firstName}}, your order update\",\n    \"html\": \"<p>Hi {{firstName}}, order #{{orderId}} has shipped.</p>\",\n    \"text\": \"Hi {{firstName}}, order #{{orderId}} has shipped.\"\n  }\n}\n```\n\nEnsure every recipient has all referenced variables defined.\n\n---\n\n## Operation Tracking\n\nAfter submitting a send, use the Operation resource to monitor batch status.\n\n1. Submit email via `POST /v1/emails` — response includes `operationId` and `operationLocation`\n2. Poll status via `GET` to the `operationLocation` URI\n3. The operation tracks progress for the entire batch\n\nThis is especially important for large recipient lists where processing is not instantaneous.\n\n---\n\n## Error Codes\n\n| Status Code | Description | Action |\n|-------------|-------------|--------|\n| **202** | Accepted | Request accepted, Operation created. Poll `operationLocation` for status. |\n| **400** | Bad Request | Malformed or ambiguous request content. Check JSON payload. |\n| **401** | Unauthorized | Verify Account SID and Auth Token / API Key are correct. |\n| **429** | Too Many Requests | Rate limited. Back off and retry. |\n| **500** | Internal Server Error | Twilio server-side issue. Retry with backoff. |\n| **503** | Service Unavailable | Temporarily unavailable. Retry after a short delay. |\n\nValidation errors return as many issues as possible in a single response to help debug quickly.\n\n---\n\n## CANNOT\n\n- **Cannot use SendGrid API keys** — Twilio Email uses Twilio Account SID + Auth Token or API Key SID + Secret. `SG.`-prefix keys do not work. Use `twilio-sendgrid-email-send` for SendGrid.\n- **Cannot send more than 10,000 recipients per request** — Split into multiple requests for larger lists.\n- **Cannot exceed 10MB per message** — Total size including attachments must be under 10MB (smaller than SendGrid's 30MB limit).\n- **Cannot use Unicode in the `from` field** — Unicode encoding is not supported for sender addresses.\n- **Cannot use Handlebars templating** — Twilio Email uses Liquid, not Handlebars. If you see `{{#if}}` or `{{#each}}`, that's Handlebars/SendGrid syntax.\n- **Cannot get synchronous delivery confirmation** — The API is async. `202 Accepted` means queued, not delivered. Poll the Operation resource for status.\n- **Tags total length cannot exceed 10,000 bytes** — Combined length of all tags on a request is limited.\n\n---\n\n## Next Steps\n\n- **Account setup and credentials:** `twilio-account-setup`\n- **SendGrid email (separate product):** `twilio-sendgrid-email-send`\n- **SMS sending:** `twilio-sms-send-message`\n"
}