Team

Un workspace si può condividere con altre persone. Questa pagina descrive chi può fare cosa, come funzionano gli inviti, quante persone ammette ogni piano e come finisce l'accesso.

Ruoli

Un workspace ha due ruoli:

Chi accetta un invito diventa sempre member. La dashboard non ha altri ruoli e non cambia i ruoli.

Alcune azioni spettano solo al proprietario. Un membro che le tenta riceve 403 FORBIDDEN con il messaggio Only the workspace owner can do this.:

• Chiavi API: elencarle, crearle, modificarle e revocarle
• Domini di invio: aggiungerli, verificarli e rimuoverli (i membri possono comunque leggerli)
• Webhook: leggerli, registrarli, modificarli ed eliminarli
• Billing: leggere piano e consumi, avviare un checkout, aprire il portale di fatturazione
• Impostazioni del workspace: modificarlo o eliminarlo, cambiarne il logo e le preferenze

Le chiavi API non sono toccate: una chiave mantiene i permessi con cui è stata creata, chiunque l'abbia creata. Vedi Permessi.

Per conoscere il tuo ruolo prima di provare, leggi role nella risposta di GET /v1/workspace (lo stesso oggetto arriva da PATCH /v1/workspace e, con 201, da POST /v1/workspaces): owner per il proprietario autenticato, member per ogni altra persona autenticata, null quando la chiamata usa una chiave API.

Il piano e le sue quote appartengono all'account del proprietario: ciò che invia un membro consuma la quota mensile di email del proprietario. Vedi Rate Limit.

Invitare qualcuno

Solo il proprietario del workspace può invitare persone, e solo dalla dashboard, in Impostazioni → Team. Le chiavi API non possono invitare nessuno, qualunque permesso abbiano.

Inserisci l'indirizzo email della persona da invitare. Riceverà un'email con un link per accettare l'invito.

Il link dell'invito

• È personale. Accettarlo conferma anche l'indirizzo email a cui è stato inviato: l'account risulta verificato senza un'email di verifica a parte. Non inoltrarlo.
• Scade dopo 7 giorni. Dopo, il proprietario invia un invito nuovo.
• Vale una volta. Un link già usato viene rifiutato, tranne che per l'account che lo ha accettato, finché ne è membro: accettarlo di nuovo riesce e non cambia nulla.
• Smette di funzionare quando l'invito viene revocato.

Cosa succede a chi accetta

• Entra nel workspace come member.
• Può aprire la dashboard anche senza un proprio accesso alla beta.
• Se il suo account possiede già un workspace o appartiene a un altro, lo tiene: la sessione passa sul workspace in cui è entrato, e il selettore della dashboard lo riporta agli altri (vedi Workspace).

Quante persone ammette ogni piano

Il piano dell'account che possiede il workspace stabilisce quanti membri del team può avere. I membri del team del tuo piano sono condivisi da tutti i workspace che possiedi. Una persona in più workspace conta una volta. Il conteggio include il proprietario (una persona) e gli inviti in attesa:

Come la quota mensile di email, questo limite appartiene all'account ed è condiviso da tutti i suoi workspace (richiede l'API 0.28.0 o successiva; prima valeva per ogni workspace separatamente). Un invito in attesa occupa il suo posto dal momento in cui viene creato. Il limite viene controllato quando il proprietario invia un invito e di nuovo quando l'invito viene accettato: se nel frattempo il posto è stato preso, la persona invitata non può entrare finché il proprietario non ne libera uno. Oltre il limite, entrambe le chiamate rispondono 429 con QUOTA_EXCEEDED.

Se un account è già oltre il limite, per esempio dopo un downgrade, nessuno viene rimosso: le nuove persone non possono essere invitate finché il conteggio non torna sotto il limite.

Per liberare un posto, revoca un invito in attesa o rimuovi un membro. Per alzare il limite, passa a un piano superiore da Impostazioni → Fatturazione.

GET /v1/workspace restituisce il limite come limits.membersPerAccount, accanto a emailsPerMonth e domains. limits.membersPerWorkspace viene ancora restituito con lo stesso numero, mantenuto per compatibilità: leggi membersPerAccount.

Inviti in attesa

Impostazioni → Team elenca i membri del workspace e gli inviti ancora in attesa. Da lì il proprietario può revocare un invito in attesa: il link smette di funzionare, e la persona invitata non riceve alcuna email.

Rimuovere un membro

Il proprietario rimuove i membri dalla dashboard. Il membro rimosso perde subito l'accesso e riceve un'email; il suo account Tratto resta attivo. Il proprietario non può essere rimosso. Vedi Workspace.

Accedere di nuovo

Dopo una revoca delle sessioni di un account (un cambio password, o l'uscita da tutti i dispositivi), le sessioni iniziate prima della revoca non aprono più il workspace: la dashboard chiede di accedere di nuovo.

Dall'API

La dashboard usa queste rotte:

Le prime quattro accettano solo la sessione della dashboard del proprietario. Una chiave API riceve sempre 403 FORBIDDEN con il messaggio Only the workspace owner can do this., qualunque permesso abbia. Per questo inviteMember e removeMember nell'SDK Node.js, e invite_member e remove_member nell'SDK Python, non possono riuscire: usa la dashboard.

Nessuna rotta elenca i membri di un workspace: l'elenco è nella dashboard, in Impostazioni → Team.

Inviare un invito

{ "email": "ada@example.com", "role": "member" }

Una richiesta riuscita risponde 201 Created:

{
  "data": {
    "id": "3f9c0a7e5b2d4c1f8e6a9b0d7c5e3f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e",
    "email": "ada@example.com",
    "invitedAt": "2026-10-06T09:30:00.000Z",
    "expiresAt": "2026-10-13T09:30:00.000Z"
  }
}

L'id è di 64 caratteri esadecimali. La risposta non contiene il token dell'invito: il token viaggia solo nell'email alla persona invitata, nel frammento del link (https://app.tratto.email/invite?tenant=…#token=…), così non finisce nei log dei server.

GET /v1/workspace/invites risponde 200 con gli stessi oggetti in data: solo inviti in attesa e non scaduti, ordinati per invitedAt. DELETE /v1/workspace/invites/:id risponde 204.

Accettare un invito

La pagina dell'invito chiama lookup e accept senza chiave API. Entrambe prendono l'id del workspace e il token del link nel corpo della richiesta:

{ "tenantId": "ws_abc123", "token": "…" }

Errori

Il corpo di QUOTA_EXCEEDED indica il piano e il limite:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Member limit reached for the starter plan: 2 people in this workspace, counting pending invites.",
    "docs": "https://docs.tratto.email/en/docs/error-codes",
    "suggestion": "Revoke a pending invite or remove a member, or upgrade the plan at https://app.tratto.email/settings/billing."
  }
}

Vedi Codici di Errore per il formato del corpo d'errore.

Prossimo: Workspace · Codici di Errore