Organization access
One call tells an agent whether it can go on with a setup. It returns the plan, whether mailboxes can be created, the trial, and how many mailboxes fit. It never returns payment methods, invoices or billing provider IDs.
Last updated
Request
GET
/v1/organization/accessAny credential of the organization can call it, including an agent connection with the Set up permissions. It answers for the credential's own organization. For a connection that covers several organizations, send X-Shipmail-Organization. The MCP tool is shipmail_get_organization_access.
Response
{
"object": "organization_access",
"organization": { "id": "org_abc123", "name": "Acme", "default_timezone": "Europe/Paris" },
"plan": "team",
"has_access": true,
"trial": { "active": true, "ends_at": "2026-10-19T09:00:00.000Z", "eligible": false },
"mailboxes": { "limit": 3, "used": 1 },
"newsletters_allowed": true
}| Field | Type | Description |
|---|---|---|
| organization | object | The organization's id, name and default_timezone (an IANA zone, or null for Etc/UTC). |
| plan | string | free, solo, pro, team or scale. |
| has_access | boolean | True when you can create a mailbox right now. It runs the same check as mailbox creation. |
| trial.active | boolean | A trial is running. |
| trial.ends_at | string | null | When the trial ends, in ISO 8601 UTC. |
| trial.eligible | boolean | No subscription yet and the owner never had a trial. Checkout still confirms it. |
| mailboxes.limit | integer | Mailboxes the organization can hold now. At most 3 in a trial. |
| mailboxes.used | integer | Mailboxes it holds, counting creates in progress. |
| newsletters_allowed | boolean | Newsletter sending is available. A trial sends newsletters within its trial limits. |
Wait for the owner to pay
- Send the owner the billing link from the agent setup steps. The owner reviews the price and pays in Shipmail.
- Poll this endpoint every 10 seconds. Access appears once Shipmail has recorded the payment, a few seconds after checkout.
- Then create mailboxes up to
mailboxes.limit.
Examples
curl https://shipmail.to/api/v1/organization/access \
-H "Authorization: Bearer <token>"