Invoice e-mail
Send invoice e-mail
Accepts sending an authorized document to the customer by e-mail; delivery is asynchronous.
/openapi/v2/empresas/{empresaId}/emailstoken, timestamp and sign signature headers, see Authentication.Sends an already authorized document (NF-e, NFS-e, CT-e or DC-e) by e-mail, with the template body and, if requested, the PDF and XML attached. The call is asynchronous: HTTP 200 returns the emailId and the acceptance status; the outcome arrives through email.sent / email.failed or through the query. id is the idempotency key; while an e-mail of the same document is in flight, another send answers 409. The document is only sent when you call this endpoint: nothing goes out automatically on authorization.
Path parameters
empresaId* | string | Company identifier |
* Required field
Request body
id* | string | Request identifier |
tipoDocumento* | string | Document type |
documentoId* | string | Document identifier |
templateId | string | Template identifier |
enviarPdf* | bool | Attach PDF |
enviarXml* | bool | Attach XML |
destinatarios | array | Recipients |
* Required field
emailId for the query; follow the outcome through the webhook or the query.emailId | string | E-mail identifier |
id | string | Request identifier |
status | string | Status at acceptance |
tipoDocumento | string | Document type |
documentoId | string | Document identifier |
templateId | string | Template used |
destinatarios | array | Effective recipients |
anexos | array | Requested attachments |
HTTP 200 is only the acceptance: the e-mail is built and sent afterwards by a platform task. The sender is the platform address (your own domain cannot be used); the display name is the company legal name and the reply-to is the company registered e-mail. The outcome arrives through email.sent / email.failed (explicit subscription, see Register webhook) or through the query.
Body and XML only
NFS-e with a chosen template and an explicit recipient; enviarPdf = false skips DANFSe generation. The attached XML is named NFSe-{chave}.xml.
{"id": "mail-nfse-000123","tipoDocumento": "NFSe","documentoId": "PED-20260918-001","templateId": "2103150000000000002","enviarPdf": false,"enviarXml": true,"destinatarios": ["financeiro@cliente.com.br"]}
id* | string | Request identifier |
tipoDocumento* | string | Document type |
documentoId* | string | Document identifier |
templateId | string | Template identifier |
enviarPdf* | bool | Attach PDF |
enviarXml* | bool | Attach XML |
destinatarios | array | Recipients |
* Required field
PDF and XML to the e-mail on the document
Without destinatarios the platform uses the customer e-mail given at issuance; only NF-e and NFS-e carry it, CT-e and DC-e require destinatarios. Without templateId it uses the default template of the type. If the PDF or the XML is not available yet, the e-mail waits in Aguardando instead of going out incomplete.
{"id": "email-pedido-8842-1","tipoDocumento": "NFe","documentoId": "pedido-8842","enviarPdf": true,"enviarXml": true}
id* | string | Request identifier |
tipoDocumento* | string | Document type |
documentoId* | string | Document identifier |
enviarPdf* | bool | Attach PDF |
enviarXml* | bool | Attach XML |
* Required field
São Paulo NFS-e waiting for the key
An NFS-e from the São Paulo municipal system gets its 50-digit key later, through the national environment. Until it arrives, the send is accepted as Aguardando with motivoEspera = chaveAcesso and rechecked every 30 seconds, for up to 120 minutes; after that it becomes Falha and motivoFalha says what was missing. The response below is the acceptance one.
{"emailId": "2103160000000000002","id": "mail-sp-000045","status": "Aguardando","tipoDocumento": "NFSe","documentoId": "SP-20260928-045","templateId": "2103150000000000002","destinatarios": ["financeiro@cliente.com.br"],"anexos": ["pdf", "xml"]}
status* | string | Status at acceptance |
* Required field
Same document in flight: 409
While an e-mail of the same document (same company, tipoDocumento and documentoId) has not reached Enviado or Falha, a new send with another id is refused with HTTP 409 and 10021015; the message carries the emailId and status of the in-flight e-mail. Wait for the callback or query, then resend with a new id.
[{"codigo": "10021015","mensagem": "O e-mail anterior desta nota ainda não foi concluído: emailId=2103160000000000001 status=Enfileirado"}]
Idempotent replay
Repeating a call with the same id (within the same company) returns the original result without creating another e-mail, even if the body differs; status reflects the current state. To send the same document again use a new id after the terminal state.
{"emailId": "2103160000000000001","id": "email-pedido-8842-1","status": "Enviado","tipoDocumento": "NFe","documentoId": "pedido-8842","templateId": "2103150000000000001","destinatarios": ["comprador@exemplo.com"],"anexos": ["pdf", "xml"]}
status* | string | Status at acceptance |
* Required field
Aguardando ──► Enfileirado ──► Enviando ──┬─► Enviado└─► Falha
Aguardando only exists while the key, the PDF or the XML is missing; it does not consume attempts. Enviando that fails on the way out goes back to Enfileirado with growing backoff, up to 5 attempts. Enviado and Falha are terminal and release the document for a new send. The meaning of each status and of motivoEspera is in Query e-mail.
tipoDocumentoDocument type
| Values | Meaning |
|---|---|
| NFe | NF-e, goods invoice |
| NFSe | NFS-e, service invoice |
| CTe | CT-e, transport document |
| DCe | DC-e, content declaration |
statusE-mail status
On the first acceptance only Aguardando or Enfileirado; the others appear on an idempotent replay.
| Values | Meaning |
|---|---|
| Aguardando | Accepted, waiting for document data; motivoEspera says what |
| Enfileirado | Queued, data complete, waiting to be sent |
| Enviando | A worker is rendering and sending |
| Enviado | Handed to the mail service; terminal |
| Falha | Final failure; motivoFalha explains; terminal |
anexos[]Attachments
File name: {tipo}-{chave}.pdf / .xml, for example NFSe-3550...077.xml.
| Values | Meaning |
|---|---|
| PDF voucher: DANFE, DANFSe, DACTE or DACE | |
| xml | Authorized XML, the legal original |
| Code | HTTP | |
|---|---|---|
| 10001001 | 400 | Field validation failed: id or documentoId blank or over 64, tipoDocumento outside the values, enviarPdf / enviarXml missing, more than 5 recipients or an invalid e-mail; one entry per field. |
| 10003000 | 404 | empresaId not found. |
| 10021001 | 404 | E-mail template not found: the templateId does not exist or does not belong to this integrator. |
| 10021002 | 400 | E-mail template disabled, or the template document type differs from the document. |
| 10021010 | 404 | Document not found or does not belong to this company. Check documentoId, tipoDocumento and empresaId. |
| 10021011 | 400 | Document not authorized yet, it cannot be sent to the customer; also for a cancelled or replaced document. Wait for authorization. |
| 10021012 | 400 | The document type has no default template; pass templateId or mark a template with padrao = true. |
| 10021013 | 400 | No recipient: destinatarios not given and the document has no customer e-mail. CT-e and DC-e always require destinatarios. |
| 10021015 | 409 | The previous e-mail for this document has not finished yet; the message carries emailId and status. Wait for Enviado or Falha and resend with a new id. |