# API email

> Invia email transazionali con una sola richiesta HTTPS, poi programmale, annullale, ritentale o inoltrale. URL di base, autenticazione, funzioni e limiti.

L’API email invia email dalla tua applicazione tramite HTTPS invece che con una connessione SMTP. Usala per le email transazionali come conferme di registrazione, reimpostazioni della password, ricevute e avvisi, soprattutto quando ti servono template, programmazione, nuovi tentativi idempotenti e un ID separato per ogni destinatario.

## Come funziona

1. La tua applicazione chiama `POST /emails` con un indirizzo From su un dominio di invio verificato, i destinatari e il contenuto o un template.
2. Emailit convalida la richiesta, addebita 1 credito per destinatario e crea un’email per ogni destinatario, ciascuna con il proprio ID `em_`.
3. La risposta arriva subito con lo stato `accepted`, oppure `scheduled` se hai impostato un orario di invio. La consegna avviene in background.
4. Emailit firma il messaggio con DKIM per il tuo dominio, esegue i controlli antispam e lo consegna. Gli errori temporanei vengono ritentati per circa 21 ore.
5. Ogni cambio di stato compare in **Email API → Emails** e viene inviato ai tuoi [webhook](/it/docs/webhooks/).

## URL di base e autenticazione

| Elemento | Valore |
| --- | --- |
| URL di base | `https://api.emailit.com/v2` |
| Autenticazione | `Authorization: Bearer secret_••••` con una [chiave API](/it/docs/developers/api-keys/) |
| Corpo della richiesta | JSON, inviato con `Content-Type: application/json` |
| Endpoint di invio | `POST /emails` |

Una chiave **Full Access** può chiamare ogni endpoint. Una chiave **Sending Only** può inviare, riprogrammare, annullare, ritentare e inoltrare email, e puoi limitarla a un solo dominio di invio. Vedi [Autenticazione](/it/docs/api-reference/authentication/) per i dettagli.

## Invia un’email

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up, Ada.</p>",
    "text": "Thanks for signing up, Ada."
  }'
```

**Node.js**

```javascript
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  subject: 'Welcome to Acme',
  html: '<p>Thanks for signing up, Ada.</p>',
  text: 'Thanks for signing up, Ada.',
});

console.log(email.id);
```

**Python**

```python
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Welcome to Acme",
    "html": "<p>Thanks for signing up, Ada.</p>",
    "text": "Thanks for signing up, Ada.",
})
```

**PHP**

```php
$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Welcome to Acme',
    'html' => '<p>Thanks for signing up, Ada.</p>',
    'text' => 'Thanks for signing up, Ada.',
]);
```

Una richiesta riuscita restituisce `200` con la nuova email:

```json
{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "token": "33VtK8m4XcPq2RwZ7nLb1YsTgHd",
  "message_id": "<33VtK8m4XcPq2RwZ7nLb1YsTgHd@acme.com>",
  "from": "Acme <hello@acme.com>",
  "to": ["ada@example.com"],
  "subject": "Welcome to Acme",
  "status": "accepted",
  "scheduled_at": null,
  "created_at": "2026-10-01T09:30:12.418203Z",
  "tracking": { "loads": false, "clicks": false }
}
```

I nuovi workspace partono in modalità sandbox e possono inviare solo agli indirizzi email degli account dei membri del workspace. [Richiedi l’accesso alla produzione](/it/docs/workspaces/production-access/) prima di inviare a chiunque altro.

## Cosa puoi fare

  - [Invia un’email](/it/docs/email-api/send-email/): Indirizzi From, destinatari, contenuto, template, tracciamento e tutti gli errori.
  - [Allegati](/it/docs/email-api/attachments/): Allega file in base64 o da un URL, e incorpora immagini inline.
  - [Programmazione](/it/docs/email-api/scheduling/): Invia più tardi, riprogramma o annulla un’email prima che parta.
  - [Idempotenza](/it/docs/email-api/idempotency/): Ritenta le richieste in sicurezza senza inviare due volte la stessa email.
  - [Header e metadati](/it/docs/email-api/headers-and-metadata/): Header personalizzati, List-Unsubscribe e metadati restituiti nei webhook.
  - [Ritenta e inoltra](/it/docs/email-api/retry-and-forward/): Reinvia email non riuscite o trattenute, oppure inoltra un’email inviata a un’altra persona.
  - [Template](/it/docs/templates/): Salva i layout una volta e inviali per alias con le variabili Temple.
  - [Riferimento API delle email](/it/docs/api-reference/emails/): Ogni endpoint delle email con parametri e risposte.

## Limiti

| Limite | Valore |
| --- | --- |
| Destinatari per richiesta | 50 in `to`, 50 in `cc` e 50 in `bcc` |
| Dimensione del messaggio | 40 MB, allegati codificati compresi |
| Allegato scaricato da un URL | 25 MB, con un timeout di download di 30 secondi |
| Finestra di idempotenza | 24 ore |
| Frequenza di invio (predefinita) | 2 email al secondo e 5000 email al giorno per workspace, condivise con SMTP |
| Inoltro | 3 inoltri all’ora per workspace |
| Riprogrammare o annullare un’email programmata | Fino a 3 minuti prima dell’orario di invio |
| Finestra per i nuovi tentativi | 30 giorni dalla creazione dell’email originale |

I limiti di frequenza contano i destinatari, quindi una richiesta a 10 destinatari usa 10 unità della tua quota al secondo e giornaliera. I workspace Pro e Business ottengono aumenti automatici in base alla salute degli invii, e qualsiasi workspace può chiederne di più dal riquadro **Sending Limits** nella home del pannello. Vedi [Limiti e quote](/it/docs/limits/) e [Limiti di frequenza](/it/docs/api-reference/rate-limits/).

## Crediti

Ogni destinatario costa 1 credito, e contano tutti gli indirizzi in `to`, `cc` e `bcc`. Se il workspace non ha crediti sufficienti per tutti i destinatari, la richiesta non riesce con `402` e non viene inviato nulla. I nuovi tentativi e gli inoltri vengono addebitati come nuovi invii.

| Azione | Crediti |
| --- | --- |
| Email inviata con l’API o SMTP (per destinatario) | 1 |
| Email in entrata ricevuta | 1 |
| Email di una campagna (per destinatario) | 2 |
| Esecuzione di un’automazione | 3 |
| Verifica email (per indirizzo) | 5 |

Vedi [Crediti](/it/docs/billing/credits/) per come vengono usati i crediti inclusi e quelli acquistati.

## Passaggi successivi

  - [Invia la prima email con l’API](/it/docs/quickstart/api/): Invia la tua prima email in pochi minuti.
  - [Aggiungi un dominio di invio](/it/docs/domains/add-a-domain/): Verifica il dominio da cui invii.
  - [Configura un webhook](/it/docs/webhooks/set-up/): Ricevi gli eventi di consegna, bounce ed engagement.
  - [API o SMTP](/it/docs/get-started/api-or-smtp/): Confronta l’API email con l’SMTP relay.

---
Fonte: https://emailit.com/it/docs/email-api/