Invia email, consulta i messaggi e il loro contenuto, e programmali, annullali, ritentali o inoltrali.
Invia un’email
Invia un’email da un dominio di invio verificato. Ogni destinatario riceve una copia separata con un proprio ID email, e ogni destinatario costa un credito.
/emailsFunziona con le chiavi API sending e full. Gli invii rientrano nei limiti di invio del workspace, e una risposta riuscita significa che l’email è stata accettata e messa in coda, non che è già stata consegnata. Segui la consegna con i webhook o con Recupera un’email. I workspace non verificati possono inviare solo agli indirizzi email degli account dei loro membri.
Header
Idempotency-KeystringUna chiave univoca, fino a 256 caratteri tra lettere, cifre, - e _. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la prima risposta invece di inviare di nuovo. Vedi Idempotenza.
Parametri del corpo
fromstringobbligatorioIl mittente, nella forma hello@acme.com o Acme <hello@acme.com>. L’indirizzo deve appartenere a un dominio di invio verificato del workspace e, se la chiave è limitata a un dominio, al dominio della chiave.
tostring | string[]obbligatorioI destinatari, come array o come stringa separata da virgole. Ogni voce può essere ada@example.com o Ada Lovelace <ada@example.com>. Fino a 50.
ccstring | string[]bccstring | string[]reply_tostring | string[]subjectstringtemplate.htmlstringhtml, text o entrambi, a meno che il contenuto non lo fornisca template.textstringhtml sia text, i destinatari ricevono un messaggio multipart.templatestringUn template da inviare. Passa un ID di template (tem_…) per usare esattamente quella versione, oppure un alias per usarne la versione pubblicata. subject, html e text nella richiesta sostituiscono quelli del template. Vedi Template.
variablesobjectI valori per i segnaposto di Temple come {{first_name}}, elaborati nell’oggetto, nell’HTML e nel testo. Funziona con i template e con il contenuto inline.
attachmentsobject[]headersobjectHeader MIME aggiuntivi come coppie nome–valore, ad esempio {"List-Unsubscribe": "<https://acme.com/unsubscribe>"}. Il Message-ID lo imposta Emailit.
metaobjectI tuoi dati chiave–valore, ad esempio {"order_id": "1042"}. I valori devono essere stringhe. Vengono salvati con l’email e inclusi nelle letture e nei payload dei webhook.
scheduled_atstringQuando inviare, come data e ora ISO 8601, ad esempio 2026-10-02T09:00:00Z, oppure in inglese, ad esempio tomorrow at 9am. Nei valori ISO 8601 includi un fuso orario. Un orario nel passato, o un valore che non è interpretabile (compreso un timestamp Unix), invia subito l’email. Le email programmate hanno lo stato scheduled finché non vengono inviate.
trackingboolean | objectAttiva o disattiva il tracciamento delle aperture e dei clic per questa email: true, false o {"loads": true, "clicks": false}. Per impostazione predefinita usa le impostazioni del dominio di invio. Il tracciamento funziona solo quando il CNAME di tracciamento del dominio è verificato; altrimenti è disattivato e la risposta mostra false.
Oggetto allegato
filenamestringobbligatoriocontentstringcontent o url, non entrambi.urlstringUn URL pubblico http o https da cui scaricare il file. Emailit lo scarica al momento dell’invio: il download deve terminare entro 30 secondi, non deve superare i 25 MB e non deve passare per reindirizzamenti.
content_typestringapplication/pdf. Obbligatorio con content. Con url, per impostazione predefinita è il tipo restituito dal server.content_idstringRende l’allegato inline. Nell’HTML fai riferimento a esso con <img src="cid:logo"> quando content_id è logo.
encodingstringpredefinito: base64content, ad esempio base64 o hex.L’intero messaggio, allegati compresi, può arrivare a 40 MB. Sono consentiti questi tipi di file:
| Categoria | Estensioni |
|---|---|
| Testo | .txt, .csv, .log, .css, .ics, .xml |
| Immagini | .jpg, .jpe, .jpeg, .gif, .png, .bmp, .psd, .tif, .tiff, .svg, .indd, .ai, .eps |
| Documenti | .doc, .docx, .rtf, .odt, .ott, .pdf, .pub, .pages, .mobi, .epub |
| Audio | .mp3, .m4a, .m4v, .wma, .ogg, .flac, .wav, .aif, .aifc, .aiff |
| Video | .mp4, .mov, .avi, .mkv, .mpeg, .mpg, .wmv |
| Fogli di calcolo | .xls, .xlsx, .ods, .numbers |
| Presentazioni | .odp, .ppt, .pptx, .pps, .key |
| Archivi | .zip, .vcf |
.eml |
|
| Crittografia | .p7c, .p7m, .p7s, .pgp, .asc, .sig |
Restituisce
Restituisce 200 con l’oggetto email del primo destinatario. Quando il messaggio ha più di un destinatario tra to, cc e bcc, ids associa ogni destinatario all’ID della sua copia. Ogni copia genera un evento email.accepted o email.scheduled.
objectstringemail.idstringidsobjecttokenstringmessage_idstringMessage-ID della prima email, ad esempio <token@acme.com>.fromstringtostring[]to, senza nomi visualizzati né duplicati.ccstring[]cc. Presente solo se li hai inviati.bccstring[]bcc. Presente solo se li hai inviati.subjectstringstatusstringaccepted, oppure scheduled per uno scheduled_at futuro.scheduled_atstring | nullnull.created_atstringtrackingobjectloads e clicks.curl -X POST 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",
"template": "welcome",
"variables": {
"first_name": "Ada",
"activation_url": "https://acme.com/activate?token=8f2c1e"
}
}'const email = await emailit.emails.send({
from: 'Acme <hello@acme.com>',
to: 'ada@example.com',
template: 'welcome',
variables: {
first_name: 'Ada',
activation_url: 'https://acme.com/activate?token=8f2c1e',
},
});email = client.emails.send({
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"template": "welcome",
"variables": {
"first_name": "Ada",
"activation_url": "https://acme.com/activate?token=8f2c1e"
}
})curl -X POST https://api.emailit.com/v2/emails \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme Billing <billing@acme.com>",
"to": "ada@example.com",
"subject": "Your invoice INV-1042",
"html": "<img src=\"cid:logo\"><p>Your invoice is attached.</p>",
"attachments": [
{
"filename": "INV-1042.pdf",
"content": "JVBERi0xLjQKJcOkw7zDqc...",
"content_type": "application/pdf"
},
{
"filename": "logo.png",
"url": "https://acme.com/assets/logo.png",
"content_id": "logo"
}
]
}'import { readFile } from 'node:fs/promises';
const pdf = await readFile('INV-1042.pdf');
const email = await emailit.emails.send({
from: 'Acme Billing <billing@acme.com>',
to: 'ada@example.com',
subject: 'Your invoice INV-1042',
html: '<img src="cid:logo"><p>Your invoice is attached.</p>',
attachments: [
{
filename: 'INV-1042.pdf',
content: pdf.toString('base64'),
content_type: 'application/pdf',
},
{
filename: 'logo.png',
url: 'https://acme.com/assets/logo.png',
content_id: 'logo',
},
],
});import base64
with open("INV-1042.pdf", "rb") as f:
pdf = base64.b64encode(f.read()).decode()
email = client.emails.send({
"from": "Acme Billing <billing@acme.com>",
"to": "ada@example.com",
"subject": "Your invoice INV-1042",
"html": '<img src="cid:logo"><p>Your invoice is attached.</p>',
"attachments": [
{"filename": "INV-1042.pdf", "content": pdf, "content_type": "application/pdf"},
{"filename": "logo.png", "url": "https://acme.com/assets/logo.png", "content_id": "logo"}
]
})curl -X POST https://api.emailit.com/v2/emails \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reminder-appt-5531" \
-d '{
"from": "Acme <reminders@acme.com>",
"to": "ada@example.com",
"subject": "Your appointment tomorrow",
"text": "See you tomorrow at 2 PM.",
"scheduled_at": "2026-10-02T09:00:00Z",
"meta": { "appointment_id": "5531" }
}'const email = await emailit.emails.send({
from: 'Acme <reminders@acme.com>',
to: 'ada@example.com',
subject: 'Your appointment tomorrow',
text: 'See you tomorrow at 2 PM.',
scheduled_at: '2026-10-02T09:00:00Z',
meta: { appointment_id: '5531' },
});email = client.emails.send({
"from": "Acme <reminders@acme.com>",
"to": "ada@example.com",
"subject": "Your appointment tomorrow",
"text": "See you tomorrow at 2 PM.",
"scheduled_at": "2026-10-02T09:00:00Z",
"meta": {"appointment_id": "5531"}
}){
"object": "email",
"id": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"ids": {
"ada@example.com": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"grace@example.com": "em_4KfIXZSV8v8L1k0Mg2YDR3rytvj"
},
"token": "4KDY1iIpQSSW5pAoiz3JEfqcsO0",
"message_id": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"from": "Acme <hello@acme.com>",
"to": ["ada@example.com", "grace@example.com"],
"subject": "Welcome to Acme",
"status": "accepted",
"scheduled_at": null,
"created_at": "2026-10-01T09:30:12.482913Z",
"tracking": {
"loads": true,
"clicks": true
}
}{
"object": "email",
"id": "em_4K76IA5sFNIsLXW9QC2ro8cDbOj",
"token": "4KWzEED2cnej6UMjF4v508VqQIp",
"message_id": "<4KWzEED2cnej6UMjF4v508VqQIp@acme.com>",
"from": "Acme <reminders@acme.com>",
"to": ["ada@example.com"],
"subject": "Your appointment tomorrow",
"status": "scheduled",
"scheduled_at": "2026-10-02T09:00:00.000Z",
"created_at": "2026-10-01T09:30:12.482913Z",
"tracking": {
"loads": false,
"clicks": false
}
}{
"error": "Validation failed",
"validation_errors": [
"Missing required field: subject",
"Invalid to email address at index 1: grace@example"
]
}{
"error": "Insufficient credits",
"message": "Insufficient credits to send this email. Required: 2, available: 0."
}{
"code": "unverified_workspace_recipient",
"error": "Workspace not verified",
"message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: grace@example.com.",
"blocked_recipients": ["grace@example.com"]
}{
"error": "Domain not authorized",
"message": "API key is not authorized to send from this domain"
}{
"error": "Template not found",
"message": "Template 'welcome' not found or not published"
}{
"error": "Message too large",
"message": "Message size (41.27MB) exceeds maximum allowed size of 40MB"
}{
"error": "Domain not verified"
}{
"error": "Rate limit exceeded",
"message": "Too many requests. Maximum 2 messages per second allowed.",
"limit": 2,
"current": 2,
"retry_after": 1
}Elenca le email
Restituisce una pagina di email, a partire dalla più recente. Per impostazione predefinita l’elenco mostra le email in uscita degli ultimi 14 giorni.
/emailsRichiede una chiave API full. In questo elenco ogni destinatario di un invio è un’email separata.
Parametri di query
pageintegerpredefinito: 1limitintegerpredefinito: 25typestringpredefinito: outbounddate_fromstringSolo le email create in questa data o dopo, ad esempio 2026-08-01 (dalle 00:00 UTC). Senza questo parametro, l’elenco parte da 14 giorni fa. I filtri created_at non cambiano questo intervallo.
date_tostringsearchstringmatchstringpredefinito: allall o or. Come si combinano i filtri qui sotto.orderstringdirectionstringasc o desc.Filtri
Aggiungi i filtri nella forma key.condition=value, ad esempio status.exact=bounced o created_at.after=2026-09-01. Per le condizioni di ciascun tipo, vedi Filtri e ordinamento.
| Chiave | Tipo | Valori e note |
|---|---|---|
to |
string | Indirizzo del destinatario. |
from |
string | Mittente così come è stato inviato, compreso l’eventuale nome visualizzato. |
subject |
string | |
status |
enum | accepted, scheduled, delivered, loaded, clicked, attempted, bounced, failed, rejected, suppressed, received, complained, canceled, held |
tag |
string | Il tag dell’email. Al momento l’invio tramite API o SMTP non imposta alcun tag. |
spam_score |
number | |
created_at |
date | |
updated_at |
date | |
api_key_id |
string | ID della chiave API che ha inviato l’email (key_…). |
sending_domain_id |
string | ID del dominio di invio (dom_…). |
Ogni chiave di filtro è anche una chiave di ordinamento. I vecchi parametri di query status, rcpt_to, mail_from, subject, api_key_id e sending_domain_id funzionano ancora: status cerca una corrispondenza esatta, mentre i parametri dell’indirizzo e dell’oggetto cercano una corrispondenza parziale.
Restituisce
Restituisce un array data di oggetti email con next_page_url e previous_page_url. Vedi Paginazione. Gli URL delle pagine non riportano i tuoi filtri, quindi richiedi la pagina successiva con i tuoi parametri e page aumentato di uno.
objectstringemail.idstringtypestringoutbound o inbound.fromstringtostringsubjectstringstatusstringsizeintegerscheduled_atstring | nullnull.created_atstringupdated_atstringmetaobject | nullmeta che hai inviato.curl -G https://api.emailit.com/v2/emails \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-d status.exact=bounced \
-d status.exact=failed \
-d match=or \
-d date_from=2026-09-01 \
-d order=created_at \
-d direction=desc{
"data": [
{
"object": "email",
"id": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"type": "outbound",
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"subject": "Welcome to Acme",
"status": "delivered",
"size": 4523,
"scheduled_at": null,
"created_at": "2026-10-01T09:30:12.482913Z",
"updated_at": "2026-10-01T09:30:14.118204Z",
"meta": null
},
{
"object": "email",
"id": "em_4KfIXZSV8v8L1k0Mg2YDR3rytvj",
"type": "outbound",
"from": "Acme <hello@acme.com>",
"to": "grace@example.com",
"subject": "Welcome to Acme",
"status": "loaded",
"size": 4527,
"scheduled_at": null,
"created_at": "2026-10-01T09:30:12.482913Z",
"updated_at": "2026-10-01T09:41:03.770521Z",
"meta": null
}
],
"next_page_url": "/app/v2/emails?page=2&limit=25",
"previous_page_url": null
}{
"statusCode": 400,
"error": "Bad Request",
"message": "Validation error",
"details": [
{
"instancePath": "/limit",
"schemaPath": "#/properties/limit/maximum",
"keyword": "maximum",
"params": { "comparison": "<=", "limit": 100 },
"message": "must be <= 100"
}
]
}Recupera un’email
Recupera un’email con lo stato, gli header già estratti, il corpo HTML e di testo e gli allegati.
/emails/{id}Richiede una chiave API full. Il contenuto dei messaggi viene conservato per il periodo di conservazione del contenuto previsto dal piano. Dopo questo periodo, headers, body e attachments sono vuoti, mentre lo stato e i metadati restano. Per recuperare solo una parte di un’email, usa Recupera il corpo, Recupera i metadati, Elenca gli allegati o Recupera il MIME grezzo.
Parametri di percorso
idstringobbligatorioem_4KYof1ZzXndZE2VPi0DgULiekG8.Restituisce
Restituisce l’oggetto email.
objectstringemail.idstringtypestringoutbound per le email che hai inviato, inbound per le email che hai ricevuto.tokenstringmessage_idstringMessage-ID.fromstringAcme <hello@acme.com>.tostringsubjectstringstatusstringLo stato attuale: accepted, scheduled, delivered, loaded, clicked, attempted, bounced, failed, rejected, suppressed, received, complained, canceled o held. Vedi Stati delle email.
sizeintegerscheduled_atstring | nullnull.created_atstringupdated_atstringtrackingobjectloads) e dei clic (clicks) è attivo.metaobject | nullmeta che hai inviato, oppure null.headersobject | nullnull dopo l’eliminazione definitiva del contenuto.bodyobjecttext e html, ciascuno una stringa o null.attachmentsobject[]Gli allegati, ciascuno con filename, content_type, size in byte, content_id (per i file inline), content_disposition (attachment o inline) e content (Base64).
{
"object": "email",
"id": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"type": "outbound",
"token": "4KDY1iIpQSSW5pAoiz3JEfqcsO0",
"message_id": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"from": "Acme Billing <billing@acme.com>",
"to": "ada@example.com",
"subject": "Your invoice INV-1042",
"status": "delivered",
"size": 48213,
"scheduled_at": null,
"created_at": "2026-10-01T09:30:12.482913Z",
"updated_at": "2026-10-01T09:30:14.118204Z",
"tracking": {
"loads": true,
"clicks": true
},
"meta": {
"invoice_id": "INV-1042"
},
"headers": {
"From": "Acme Billing <billing@acme.com>",
"To": "ada@example.com",
"Subject": "Your invoice INV-1042",
"Message-ID": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"MIME-Version": "1.0",
"Content-Type": "multipart/mixed; boundary=\"--_NmP-4f1c2a9e7b3d0e5f-Part_1\""
},
"body": {
"text": "Your invoice is attached.",
"html": "<p>Your invoice is attached.</p>"
},
"attachments": [
{
"filename": "INV-1042.pdf",
"content_type": "application/pdf",
"size": 40960,
"content_id": null,
"content_disposition": "attachment",
"content": "JVBERi0xLjQKJcOkw7zDqc..."
}
]
}{
"object": "email",
"id": "em_4KbeG9poqTmjvQZeN8pMoJkCVNd",
"type": "inbound",
"token": "4KTnDU5PzzqDqp8UWb9qVhPVFOT",
"message_id": "<CAH7x2k9@mail.example.com>",
"from": "Ada Lovelace <ada@example.com>",
"to": "support@inbound.acme.com",
"subject": "Re: Your invoice INV-1042",
"status": "received",
"size": 8234,
"scheduled_at": null,
"created_at": "2026-10-01T11:02:45.031877Z",
"updated_at": "2026-10-01T11:02:45.031877Z",
"meta": null,
"headers": {
"From": "Ada Lovelace <ada@example.com>",
"To": "support@inbound.acme.com",
"Subject": "Re: Your invoice INV-1042",
"Content-Type": "text/plain; charset=utf-8"
},
"body": {
"text": "Thanks, received.",
"html": null
},
"attachments": []
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}Recupera il MIME grezzo
Recupera il sorgente MIME completo di un’email così come è salvato da Emailit, insieme ai suoi metadati.
/emails/{id}/rawRichiede una chiave API full. Usalo per archiviare un messaggio, fare il debug della sua struttura o elaborarlo con la tua libreria MIME. Al termine del periodo di conservazione del contenuto, raw e headers sono null.
Parametri di percorso
idstringobbligatorioRestituisce
Restituisce i metadati dell’email, come in Recupera i metadati ma senza attachments, più il messaggio grezzo.
rawstring | nullnull dopo l’eliminazione definitiva del contenuto.headersobject | nullGli altri campi (object, id, type, token, message_id, from, to, subject, status, size, scheduled_at, created_at, updated_at, tracking e meta) sono gli stessi di Recupera un’email.
{
"object": "email",
"id": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"type": "outbound",
"token": "4KDY1iIpQSSW5pAoiz3JEfqcsO0",
"message_id": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"subject": "Welcome to Acme",
"status": "delivered",
"size": 1342,
"scheduled_at": null,
"created_at": "2026-10-01T09:30:12.482913Z",
"updated_at": "2026-10-01T09:30:14.118204Z",
"tracking": {
"loads": false,
"clicks": false
},
"meta": null,
"headers": {
"From": "Acme <hello@acme.com>",
"To": "ada@example.com",
"Subject": "Welcome to Acme",
"Message-ID": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"MIME-Version": "1.0",
"Content-Type": "text/html; charset=utf-8"
},
"raw": "From: Acme <hello@acme.com>\r\nTo: ada@example.com\r\nSubject: Welcome to Acme\r\nMessage-ID: <4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>\r\nMIME-Version: 1.0\r\nContent-Type: text/html; charset=utf-8\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\n<h1>Welcome!</h1><p>Thanks for signing up.</p>"
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}Elenca gli allegati
Restituisce gli allegati di un’email, compreso il loro contenuto.
/emails/{id}/attachmentsRichiede una chiave API full. Funziona per le email in uscita e in entrata. Le immagini inline (le parti con un Content-ID) sono incluse. Per ottenere l’elenco senza il contenuto dei file, usa Recupera i metadati. Al termine del periodo di conservazione del contenuto, l’elenco è vuoto.
Parametri di percorso
idstringobbligatorioRestituisce
Restituisce un oggetto di tipo list con tutti gli allegati. L’elenco non è paginato.
objectstringlist.dataobject[]data[].filenamestringdata[].content_typestringapplication/pdf.data[].sizeintegerdata[].content_idstring | nullContent-ID di un allegato inline, oppure null.data[].content_dispositionstring | nullattachment o inline.data[].contentstring{
"object": "list",
"data": [
{
"filename": "INV-1042.pdf",
"content_type": "application/pdf",
"size": 40960,
"content_id": null,
"content_disposition": "attachment",
"content": "JVBERi0xLjQKJcOkw7zDqc..."
},
{
"filename": "logo.png",
"content_type": "image/png",
"size": 5120,
"content_id": "logo",
"content_disposition": "inline",
"content": "iVBORw0KGgoAAAANSUhEUgAA..."
}
]
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}Recupera il corpo
Restituisce il corpo HTML e in testo semplice di un’email, decodificato dalle sue parti MIME.
/emails/{id}/bodyRichiede una chiave API full. Funziona per le email in uscita e in entrata. Per le email in uscita, il corpo è quello inviato, dopo l’elaborazione del template e delle variabili. Al termine del periodo di conservazione del contenuto, entrambi i campi sono null.
Parametri di percorso
idstringobbligatorioRestituisce
textstring | nullnull se l’email non ne ha.htmlstring | nullnull se l’email non ne ha.{
"text": "Welcome!\n\nThanks for signing up.",
"html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}Recupera i metadati
Recupera un’email senza il corpo: stato, header, i tuoi dati meta e l’elenco degli allegati senza il loro contenuto.
/emails/{id}/metaRichiede una chiave API full. È il modo più leggero per leggere i dettagli di un’email quando non ti serve il contenuto.
Parametri di percorso
idstringobbligatorioRestituisce
Restituisce gli stessi campi di Recupera un’email, senza body e con gli attachments descritti ma non inclusi:
attachmentsobject[]filename, content_type, size, content_id e content_disposition. Nessun content.headersobject | nullnull dopo l’eliminazione definitiva del contenuto.metaobject | nullmeta che hai inviato con l’email.{
"object": "email",
"id": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"type": "outbound",
"token": "4KDY1iIpQSSW5pAoiz3JEfqcsO0",
"message_id": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"from": "Acme Billing <billing@acme.com>",
"to": "ada@example.com",
"subject": "Your invoice INV-1042",
"status": "delivered",
"size": 48213,
"scheduled_at": null,
"created_at": "2026-10-01T09:30:12.482913Z",
"updated_at": "2026-10-01T09:30:14.118204Z",
"tracking": {
"loads": true,
"clicks": true
},
"meta": {
"invoice_id": "INV-1042"
},
"headers": {
"From": "Acme Billing <billing@acme.com>",
"To": "ada@example.com",
"Subject": "Your invoice INV-1042",
"Message-ID": "<4KDY1iIpQSSW5pAoiz3JEfqcsO0@acme.com>",
"MIME-Version": "1.0",
"Content-Type": "multipart/mixed; boundary=\"--_NmP-4f1c2a9e7b3d0e5f-Part_1\""
},
"attachments": [
{
"filename": "INV-1042.pdf",
"content_type": "application/pdf",
"size": 40960,
"content_id": null,
"content_disposition": "attachment"
}
]
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}Aggiorna un’email programmata
Sposta un’email programmata a un nuovo orario di invio.
/emails/{id}Funziona con le chiavi API sending e full. Puoi riprogrammare solo un’email con stato scheduled il cui orario di invio attuale è a più di 3 minuti da adesso. Si può cambiare solo l’orario di invio; per cambiare il contenuto, annulla l’email e inviane una nuova.
Un invio programmato a più destinatari crea un’email per ogni destinatario. Riprogramma ciascun ID della mappa ids della risposta dell’invio.
Parametri di percorso
idstringobbligatorioParametri del corpo
scheduled_atstringobbligatorioIl nuovo orario di invio, come data e ora ISO 8601, ad esempio 2026-10-03T09:00:00Z, oppure in inglese, ad esempio tomorrow at 3pm. Deve essere a più di 3 minuti nel futuro.
Restituisce
objectstringemail.idstringstatusstringscheduled.scheduled_atstringupdated_atstringmessagestringRestituisce 422 se l’email non è programmata, se mancano meno di 3 minuti all’invio, oppure se il nuovo orario non è interpretabile o è troppo vicino.
curl -X POST https://api.emailit.com/v2/emails/em_4K76IA5sFNIsLXW9QC2ro8cDbOj \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scheduled_at": "tomorrow at 3pm"}'{
"object": "email",
"id": "em_4K76IA5sFNIsLXW9QC2ro8cDbOj",
"status": "scheduled",
"scheduled_at": "2026-10-03T09:00:00.000Z",
"updated_at": "2026-10-01T10:15:40.207316Z",
"message": "Email schedule has been updated successfully"
}{
"error": "Email not found",
"message": "Email with ID 'em_4K76IA5sFNIsLXW9QC2ro8cDbOj' not found in your workspace"
}{
"error": "Cannot update email",
"message": "Email cannot be updated. Current status: 'delivered'. Only 'scheduled' emails can be updated."
}{
"error": "Cannot update email",
"message": "Scheduled emails can only be updated at least 3 minutes before the scheduled time. This email is scheduled to send in 2 minute(s)."
}{
"error": "Invalid scheduled_at",
"message": "The new scheduled time must be at least 3 minutes in the future."
}Annulla un’email
Rimuove un’email dalla coda di invio e ne imposta lo stato su canceled.
/emails/{id}/cancelFunziona con le chiavi API sending e full. L’annullamento non è garantito: toglie l’email dalla coda, ma se un tentativo di consegna è già iniziato, quel tentativo potrebbe comunque completarsi e vengono fermati solo i nuovi tentativi rimanenti. La risposta indica in in_flight quale dei due casi si applica. L’annullamento genera un evento email.canceled e il credito non viene rimborsato. L’azione Cancel delivery del pannello fa la stessa cosa.
| Stato | Annullabile | Note |
|---|---|---|
scheduled |
Sì | Fino a 3 minuti prima dell’orario programmato. |
accepted |
Sì | In coda e non ancora consegnata. |
attempted |
Sì | Ferma i nuovi tentativi rimanenti dopo un errore temporaneo. |
| Qualsiasi altro | No | L’email è già stata consegnata, non è riuscita o è stata annullata. |
Per annullare un invio con più destinatari, annulla ciascun ID della mappa ids della risposta dell’invio.
Parametri di percorso
idstringobbligatorioRestituisce
objectstringemail.idstringstatusstringcanceled.in_flightbooleantrue se un tentativo di consegna potrebbe essere già in corso e potrebbe ancora completarsi. false se l’email è stata rimossa dalla coda prima di qualsiasi tentativo.messagestring{
"object": "email",
"id": "em_4K76IA5sFNIsLXW9QC2ro8cDbOj",
"status": "canceled",
"in_flight": false,
"message": "Email has been canceled and removed from the send queue."
}{
"object": "email",
"id": "em_4K76IA5sFNIsLXW9QC2ro8cDbOj",
"status": "canceled",
"in_flight": true,
"message": "Email was canceled. The current delivery attempt may still complete; remaining retries were stopped."
}{
"error": "Email not found",
"message": "Email with ID 'em_4K76IA5sFNIsLXW9QC2ro8cDbOj' not found in your workspace"
}{
"error": "Cannot cancel email",
"message": "Email cannot be canceled. Current status: 'delivered'. Only 'scheduled', 'accepted', or 'attempted' emails can be canceled."
}{
"error": "Cannot cancel email",
"message": "Scheduled emails can only be canceled at least 3 minutes before the scheduled time. This email is scheduled to send in 2 minute(s)."
}Ritenta un’email
Mette in coda una copia di un’email che non è arrivata a destinazione. La copia è una nuova email con un proprio ID, e l’originale mantiene il suo stato.
/emails/{id}/retryFunziona con le chiavi API sending e full. La copia ha lo stesso mittente, destinatario, oggetto, contenuto, header, meta e impostazioni di tracciamento, con un nuovo Message-ID. Costa crediti come un nuovo invio: un credito, o due per un’email di una campagna.
Puoi ritentare un’email quando:
- Il suo stato è
bounced,failed,suppressedoheld. - È stata creata negli ultimi 30 giorni.
- Il suo contenuto non è stato eliminato definitivamente in base al periodo di conservazione e il suo dominio di invio esiste ancora.
Prima elimina la causa. Un indirizzo soppresso che è ancora nella lista di soppressione viene soppresso di nuovo, e un’email trattenuta viene trattenuta di nuovo finché il motivo per cui è stata trattenuta non viene risolto.
Parametri di percorso
idstringobbligatorioRestituisce
objectstringemail.idstringoriginal_idstringtokenstringmessage_idstringMessage-ID della nuova email.fromstringtostringsubjectstringstatusstringaccepted.created_atstringmessagestring{
"object": "email",
"id": "em_4KbeG9poqTmjvQZeN8pMoJkCVNd",
"original_id": "em_4KKrQ7TzsVtzsS8zG069B2aMtoK",
"token": "4KTnDU5PzzqDqp8UWb9qVhPVFOT",
"message_id": "<4KTnDU5PzzqDqp8UWb9qVhPVFOT@acme.com>",
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"subject": "Welcome to Acme",
"status": "accepted",
"created_at": "2026-10-01T12:04:51.330482Z",
"message": "Email has been queued for retry"
}{
"error": "Insufficient credits",
"message": "Insufficient credits to retry this email. Required: 1, available: 0."
}{
"error": "Email not found",
"message": "Email with ID 'em_4KKrQ7TzsVtzsS8zG069B2aMtoK' not found in your workspace"
}{
"error": "Cannot retry email",
"message": "Only bounced, failed, suppressed, or held emails can be retried. Current status: 'delivered'"
}{
"error": "Cannot retry email",
"message": "Emails older than 30 days cannot be retried"
}{
"error": "Cannot retry email",
"message": "Email raw content has been purged and can no longer be retried"
}Inoltra un’email
Invia il contenuto di un’email in uscita a nuovi destinatari come nuova email. L’email originale non cambia.
/emails/{id}/forwardFunziona con le chiavi API sending e full. Per impostazione predefinita l’inoltro è un semplice reinvio dell’HTML, del testo e degli allegati originali. Imposta include_headers per aggiungere un blocco «Forwarded message» e una nota facoltativa sopra il contenuto originale.
Un inoltro è un nuovo invio, quindi valgono le regole di Invia un’email: l’indirizzo from deve appartenere a un dominio di invio verificato, ogni destinatario costa un credito e rientra nei limiti di invio, il tracciamento segue le impostazioni del dominio e l’header Idempotency-Key è supportato. In più, un workspace può inoltrare al massimo 3 email all’ora.
Si possono inoltrare solo le email in uscita, e solo finché il loro contenuto viene conservato in base al periodo di conservazione. Per inoltrare la posta ricevuta, usa un’automazione.
Parametri di percorso
idstringobbligatorioHeader
Idempotency-KeystringParametri del corpo
tostring | string[]obbligatorioinclude_headersbooleanpredefinito: falseSe true, aggiunge un blocco «Forwarded message» con mittente, data, oggetto e destinatario originali, e sopra di esso la tua nota. Se false, reinvia il contenuto originale senza modifiche.
commentstringinclude_headers. body è accettato come alias.htmlstringcomment con escape. Usata solo con include_headers.textstringcomment. Usata solo con include_headers.fromstringfrom dell’email originale.subjectstringinclude_headers, Fwd: seguito dall’oggetto originale.Gli allegati originali sono inclusi quando il loro tipo di file è consentito.
Restituisce
Restituisce lo stesso oggetto di Invia un’email, con due campi in più:
original_idstringmessagestringOltre il limite di inoltri, l’API restituisce 429 con un header retry-after.
curl -X POST https://api.emailit.com/v2/emails/em_4KYof1ZzXndZE2VPi0DgULiekG8/forward \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fwd-inv-1042-grace" \
-d '{
"to": ["grace@example.com"],
"include_headers": true,
"comment": "Grace, here is the invoice Ada asked about."
}'const email = await emailit.emails.forward('em_4KYof1ZzXndZE2VPi0DgULiekG8', {
to: ['grace@example.com'],
include_headers: true,
comment: 'Grace, here is the invoice Ada asked about.',
});email = client.emails.forward("em_4KYof1ZzXndZE2VPi0DgULiekG8", {
"to": ["grace@example.com"],
"include_headers": True,
"comment": "Grace, here is the invoice Ada asked about."
}){
"object": "email",
"id": "em_4K76IA5sFNIsLXW9QC2ro8cDbOj",
"original_id": "em_4KYof1ZzXndZE2VPi0DgULiekG8",
"token": "4KWzEED2cnej6UMjF4v508VqQIp",
"message_id": "<4KWzEED2cnej6UMjF4v508VqQIp@acme.com>",
"from": "Acme Billing <billing@acme.com>",
"to": ["grace@example.com"],
"subject": "Fwd: Your invoice INV-1042",
"status": "accepted",
"scheduled_at": null,
"created_at": "2026-10-01T13:20:07.915203Z",
"tracking": {
"loads": true,
"clicks": true
},
"message": "Email has been queued for forwarding"
}{
"error": "Validation failed",
"validation_errors": ["Invalid to email address at index 0: grace@example"]
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}{
"error": "Cannot forward email",
"message": "Only outgoing emails can be forwarded"
}{
"error": "Cannot forward email",
"message": "Email raw content has been purged and can no longer be forwarded"
}{
"error": "too_many_requests",
"message": "Forwarding is limited to 3 emails per hour for this workspace. Try again later.",
"limit": 3,
"current": 4,
"retry_after": 2711
}Recupera solo lo stato
Restituisce solo lo stato attuale di un’email.
/email/{id}Richiede una chiave API full. Nota il singolare /email nel percorso. La risposta è piccola, quindi questo endpoint è comodo per controllare rapidamente lo stato. Per ricevere i cambi di stato nel momento in cui avvengono, usa i webhook invece del polling.
Parametri di percorso
idstringobbligatorioRestituisce
statusstringLo stato attuale: accepted, scheduled, delivered, loaded, clicked, attempted, bounced, failed, rejected, suppressed, received, complained, canceled o held. Vedi Stati delle email.
{
"status": "delivered"
}{
"error": "Email not found",
"message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}