Send documents to customers with PDF attachments and customizable templates.
Send
// title: Send invoice email
await sdk.email.sendEmail({
document_id: invoice.id,
to: "customer@example.com",
subject: "Invoice #{document_number}",
body_text: "Please find your invoice attached.",
});Uses the entity’s default email template for the document type and locale.
PDF Attachment
Control what gets attached to the email:
| Option | Type | Default | Description |
|---|---|---|---|
attach_pdf | boolean | false | Attach the document as a PDF file |
attach_eslog | boolean | false | Attach e-SLOG 2.0 XML (Slovenian format) |
language | string | entity locale | Override the PDF and shareable link language |
Both attach_pdf and attach_eslog can be combined in a single email.
Default Templates & Multi-Language
When you create an entity, default email templates are automatically generated for each document type. Templates use the entity’s locale by default.
18 locales are supported: en-US, de-DE, it-IT, fr-FR, es-ES, sl-SI, pt-PT, nl-NL, pl-PL, hr-HR, sv-SE, fi-FI, et-EE, bg-BG, cs-CZ, sk-SK, nb-NO, is-IS.
Override the language per-email by passing the language option.
Optional Customization
The basic send uses the default sender and template. Configure the following only when you need your own sender address or email copy.
Verified Custom Sender Addresses
Production entities can send document emails and payment reminders from a verified address such as billing@example.com. Configure an entity sender in Settings → Email, or use the entity sender API.
White-label account owners and admins can also configure an inherited sender in Account → White labels. White-label sender management is an account-admin dashboard feature and is not exposed through the public API.
Sender Precedence
Only a fully verified custom sender is used for delivery. The effective From address is selected in this order:
- Verified entity sender
- Verified sender inherited from the entity’s production white label
- Platform default sender
Saving a pending or failed entity sender does not interrupt delivery; Space Invoices continues using the next verified sender in the list. The sender configuration response returns configured, inherited, and effective so you can see both verification state and the address currently used.
Verification Flow
- Set the entity sender. The address is normalized and reserved to the account.
- Complete the verification message sent to the email address.
- Add the returned
domain_dkim_tokensas CNAME records in the sender domain’s DNS. - Recheck verification after DNS changes propagate. Rechecking reads status only and does not resend verification.
- Confirm that
effective.sourceisentityandeffective.verifiedistruebefore relying on the custom address.
Both the email address and its domain must be verified. Entity admins and account owners/admins can set, clear, or recheck an entity sender. Clearing an override restores sender inheritance, but intentionally does not release the address for use by another account.
The same normalized email address cannot be claimed by multiple accounts. A 409 response means the identity is already reserved; a 503 means the verification provider is temporarily unavailable and the request can be retried.
Custom Template
// title: Custom email template
await sdk.email.sendEmail({
document_id: invoice.id,
to: "billing@acme.com, accounts@acme.com",
subject: "Invoice {document_number} from {entity_name}",
body_text: `Hi {customer_name},
Please find invoice **{document_number}** attached.
**Amount due:** {total_with_tax} {currency_code}
**Due date:** {due_date}
View online: {invoice_link}
Thank you for your business!`,
});Use the template variable reference to personalize the subject and body.
Markdown Formatting
The body_text field supports Markdown formatting. Bold, italic, links, and lists all render correctly in the email. HTML tags and images are stripped for security.
Sending Limits and External Review
Suspicious sends on free and trial accounts may undergo an EU-hosted abuse review using a minimised, scrubbed email and document summary. Paid accounts and white-label sends without a classified free or trial plan are excluded from this review. Existing sending limits and other safeguards still apply; review blocks return 403 and exceeded sending limits return 429.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Variable shows as empty | Document or customer field is null | Ensure the referenced field is set before sending |
| Email not received | Recipient address invalid or blocked | Check the to address; review bounce logs in dashboard |
| Custom sender is not active | Email or domain verification is still pending | Complete email verification, add every returned DKIM CNAME record, then recheck status |
| Sender update returns 409 | The normalized address is reserved to another account | Use another controlled address or contact support if ownership needs investigation |
| Sender update returns 422 | Custom sender verification was attempted in sandbox | Configure the sender on a production entity or production white label |
| Sender update or recheck returns 503 | The verification provider is temporarily unavailable | Retry later; the existing effective sender remains in use |
| Rate limited (429) | A per-document or sandbox account send limit was reached | Wait for the returned Retry-After duration before retrying |
| PDF not attached | attach_pdf not set | Pass attach_pdf: true in the send options |
| Wrong language on PDF | Entity locale differs from customer | Pass language option to override |
Template Reference
Use this reference when writing a custom template.
Template Variables
Variables are wrapped in curly braces and replaced automatically when the email is sent.
Entity Variables
| Variable | Description |
|---|---|
{entity_name} | Your company/organization name |
{entity_email} | Entity email address |
{entity_address} | Street address |
{entity_city} | City |
{entity_post_code} | Postal/ZIP code |
{entity_country} | Country |
{entity_tax_number} | Tax/VAT number |
{entity_company_number} | Company registration number |
Document Variables
| Variable | Description |
|---|---|
{document_number} | Invoice or estimate number |
{document_date} | Issue date (localized) |
{document_due_date} | Payment due date (localized) |
{document_valid_until} | Estimate validity date (localized) |
{document_total} | Total amount with tax (2 decimal places) |
{document_currency} | Currency code (e.g., EUR, USD) |
Customer Variables
| Variable | Description |
|---|---|
{customer_name} | Customer’s name |
{customer_email} | Customer’s email |
Bank Account Variables
| Variable | Description |
|---|---|
{bank_account} | Full bank account details (multiline) |
{bank_account.iban} | IBAN |
{bank_account.account_number} | Account number |
{bank_account.bank_name} | Bank name |
{bank_account.bic} | BIC/SWIFT code |
{bank_account.name} | Account holder name |
{bank_account.routing_number} | Routing number (US) |
{bank_account.sort_code} | Sort code (UK) |
Date Variables
| Variable | Description |
|---|---|
{current_date} | Today’s date (localized) |
{current_year} | Current year |