Send email with Python through Volanea by making an authenticated JSON request from your backend. This guide uses Python’s requests library, an API key stored in an environment variable, and one copy-pasteable script that sends a transactional email.
What you will build
By the end of this guide, you will have a small Python program that does four useful things:
- Loads Volanea credentials and message settings from environment variables.
- Sends a
POSTrequest to Volanea’s transactional email endpoint. - Provides both HTML and plain-text versions of a transactional message.
- Surfaces useful error details when the API rejects or cannot process the request.
The implementation deliberately uses standard HTTPS and JSON rather than assuming a Python-only Volanea SDK. That keeps the integration straightforward, makes it easy to inspect requests in logs, and avoids tying your application to an unverified client-library method name.
This is appropriate for transactional messages that are initiated by an application event: a verification email, password-reset link, purchase receipt, account alert, invitation, or status notification. Do not place this script in browser-side code. Your Volanea API key is a server credential and must remain on infrastructure you control.
Prerequisites
Before running the example, make sure you have the following:
- Python 3.9 or later installed.
- A Volanea API key available to your server process.
- A sender address on a domain that is configured for sending in Volanea.
- A real recipient address you can access for testing.
- Network access from the machine or container running the script to Volanea’s API.
A sender address matters as much as the Python code. The from address must be one your sending setup permits. In practice, that means using an address on a domain you have authenticated rather than an arbitrary mailbox address. Authentication records and sending-domain status affect whether a provider accepts the request and whether mailbox providers trust the message after it is sent.
Keep the API key out of source control. Do not paste it directly into a Python file, commit it to a repository, or expose it through a frontend environment variable. Treat it like a password: anyone who obtains it may be able to send mail under your account.
For the current API contract, authentication requirements, and any account-specific setup details, consult the email API reference and setup guides. The Python code below uses the standard REST pattern: bearer authentication, a JSON request body, and a POST request to create an email send.
Install the Python dependencies
Install the two dependencies used in this guide:
python -m pip install requests python-dotenv
requests performs the HTTPS request. python-dotenv is used only for local development convenience: it loads values from a local .env file into the process environment. In a deployed environment, such as a container platform, CI job, or serverless function, set these variables through the platform’s secret-management or environment configuration instead of shipping a .env file.
You can confirm the installation with:
python -c "import requests; from dotenv import load_dotenv; print('Dependencies installed')"
If your system maps python to Python 2 or does not provide that command, use python3 consistently instead:
python3 -m pip install requests python-dotenv
Using python -m pip is usually safer than invoking pip directly because it installs packages into the interpreter that will run your script. It prevents a common setup problem where a package appears to install successfully but cannot be imported at runtime because it was installed into another virtual environment.
Optional: use a virtual environment
A virtual environment keeps project dependencies isolated from your system Python installation. Create and activate one before installing packages:
python -m venv .venv
source .venv/bin/activate
On Windows PowerShell, activate it with:
.venv\Scripts\Activate.ps1
Then install the dependencies inside that environment:
python -m pip install requests python-dotenv
Add .venv/ to .gitignore. A virtual environment is not required for the example to work, but it is the normal choice for application projects because it makes dependencies reproducible and avoids version conflicts between projects.
Configure environment variables
Create a file named .env in the same directory as the Python script. This file is for local development only and should never be committed.
VOLANEA_API_KEY=replace_with_your_api_key
VOLANEA_FROM=support@your-verified-domain.example
VOLANEA_TO=you@example.com
Replace the values as follows:
VOLANEA_API_KEY: your server-side Volanea API credential.VOLANEA_FROM: a sender identity associated with your configured sending domain.VOLANEA_TO: an inbox you control while testing.
VOLANEA_FROM must be a bare email address. Volanea's send API validates from as an address and rejects the Name <address> form with a 422 validation error, so the display name goes in a separate fromName field, as the script below does. The display name is optional, but it helps recipients recognize who sent the message.
Add the .env file to .gitignore immediately:
.env
For deployments, use the same variable names but set them in the runtime environment. For example, a shell session can export them before running the script:
export VOLANEA_API_KEY="replace_with_your_api_key"
export VOLANEA_FROM="support@your-verified-domain.example"
export VOLANEA_TO="you@example.com"
python send_email.py
Environment variables keep secrets separate from application code. They also make it easier to use different keys and sender addresses in local development, staging, and production without editing files.
Send email with Python
Create a file named send_email.py and paste in the complete example below.
import os
import sys
from typing import Any
import requests
from dotenv import load_dotenv
# Load .env for local development. In production, configure these values
# through your hosting platform or secret manager instead.
load_dotenv()
API_URL = "https://api.volanea.com/v1/send"
def required_env(name: str) -> str:
"""Return a required environment variable or stop with a clear error."""
value = os.getenv(name)
if not value:
raise RuntimeError(f"Missing required environment variable: {name}")
return value
def response_body(response: requests.Response) -> Any:
"""Return JSON when possible, otherwise return response text."""
try:
return response.json()
except ValueError:
return response.text
def main() -> None:
api_key = required_env("VOLANEA_API_KEY")
from_address = required_env("VOLANEA_FROM")
to_address = required_env("VOLANEA_TO")
payload = {
"from": from_address,
"fromName": "Acme Support",
"to": [to_address],
"subject": "Welcome to Acme",
"html": """
<h1>Welcome to Acme</h1>
<p>Your account is ready.</p>
<p>If you did not create this account, you can ignore this email.</p>
""",
"text": """Welcome to Acme\n\nYour account is ready.\n\nIf you did not create this account, you can ignore this email.""",
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"Accept": "application/json",
}
try:
response = requests.post(
API_URL,
headers=headers,
json=payload,
# First value is connection timeout; second is read timeout.
timeout=(3.05, 15),
)
except requests.exceptions.Timeout:
print("Request timed out while contacting Volanea.", file=sys.stderr)
sys.exit(1)
except requests.exceptions.ConnectionError as error:
print(f"Could not connect to Volanea: {error}", file=sys.stderr)
sys.exit(1)
except requests.exceptions.RequestException as error:
print(f"Unexpected HTTP client error: {error}", file=sys.stderr)
sys.exit(1)
if not response.ok:
print(f"Volanea returned HTTP {response.status_code}", file=sys.stderr)
print(response_body(response), file=sys.stderr)
sys.exit(1)
print("Email accepted by Volanea.")
print(response_body(response))
if __name__ == "__main__":
main()
Run it from the same directory as .env:
python send_email.py
If the request succeeds, the script prints an acceptance message and the API response body. Save the returned response data in application logs when appropriate. A successful API response means Volanea accepted the message for processing; it is not identical to confirmation that the recipient opened the message or that a mailbox provider placed it in the inbox.
Why the example uses json=payload
The requests library accepts a Python dictionary through its json= parameter. It serializes the dictionary into JSON and sends it as the request body. This is safer and clearer than building JSON manually as a string.
The code also sets Content-Type: application/json explicitly. This tells the API how to parse the body. Although requests supplies the header when using json=, keeping it visible in the example makes the request contract easy to inspect and helps when porting the call to another client.
Do not replace json=payload with data=payload unless you intentionally want form-encoded data. A REST endpoint expecting JSON can reject form data or interpret it incorrectly. If you use data=, you would need to serialize the JSON yourself and preserve the correct content type.
Why the example includes both HTML and text
The html field provides the formatted version recipients see in most mail clients. The text field provides a readable fallback for plain-text clients, restrictive security settings, and recipients who prefer text-only email.
Plain text is not merely a legacy fallback. It makes operational messages easier to read in terminals and accessibility tools, and it gives recipients a usable version when HTML cannot be rendered. Keep the two versions semantically aligned: the text version should communicate the same action, destination, and important details as the HTML version.
Understand the request payload
The send request contains a handful of core message fields:
{
"from": "support@your-verified-domain.example",
"fromName": "Acme Support",
"to": ["you@example.com"],
"subject": "Welcome to Acme",
"html": "<h1>Welcome to Acme</h1>",
"text": "Welcome to Acme"
}
from identifies the sender and must be a bare address on a verified domain; fromName carries the display name. Use a consistent sender identity for each message class where possible. For example, account security notices may come from security@, receipts from receipts@, and product support messages from support@. Consistency helps recipients recognize the source and helps your team identify the purpose of a message during investigations.
to is an array, even when the example sends to only one address. Keeping recipients in an array gives the request an unambiguous structure and avoids changing your integration shape when a message needs more than one direct recipient. For transactional email, however, be careful about multiple recipients: sending account-specific content to a shared recipient list can expose private information.
subject should explain the event without revealing sensitive information. “Reset your password” is generally safer than placing a password, verification code, full account number, or personal data in the subject line. Subjects may be visible in notifications, lock screens, forwarding rules, and mailbox search results.
html and text are message bodies. Generate them on the server from trusted application data. If customer-supplied content appears in HTML, escape or sanitize it before interpolation. Email HTML is not a safe place to render raw user input.
Use the send call in an application
The standalone script proves that credentials, sender configuration, network access, and request shape are working. In an application, move the call into a small service function rather than duplicating the HTTP request throughout route handlers, jobs, and business-logic modules.
A focused function creates one place to manage timeouts, logging, retry policy, and payload validation. It also makes testing easier because your application can mock a single send boundary rather than every external request.
from typing import Any
import requests
VOLANEA_SEND_URL = "https://api.volanea.com/v1/send"
def send_transactional_email(
*,
api_key: str,
from_address: str,
recipient: str,
subject: str,
html: str,
text: str,
) -> dict[str, Any]:
response = requests.post(
VOLANEA_SEND_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"Accept": "application/json",
},
json={
"from": from_address,
"to": [recipient],
"subject": subject,
"html": html,
"text": text,
},
timeout=(3.05, 15),
)
response.raise_for_status()
return response.json()
Call this function after the business event has been recorded successfully. For example, when sending a receipt, persist the completed payment or order state first, then request the email send. That ordering prevents a confusing situation where a receipt is sent for an operation that later rolls back.
For important messages, do not rely solely on an in-memory request inside a web handler. A durable job or outbox pattern is generally safer. Write an “email needs sending” record as part of the same database transaction as the user action, then let a worker send it and record the result. This approach improves resilience when an HTTP request times out, a worker restarts, or a deployment interrupts a request.
If you use Django, Flask, or FastAPI, the framework guides show where this function fits: Django, Flask, and FastAPI.
Send email with Python's standard library: smtplib and email
Python can send email with no third-party packages at all. Two standard-library modules split the job: the email package builds the message (headers, plain-text and HTML parts, attachments), and smtplib hands it to an SMTP server. This is the right choice when you cannot add dependencies, when a framework already expects SMTP, or when you are writing a quick script. Volanea accepts SMTP as well as the REST API: log in with the username volanea and your secret API key as the password, and copy the host and port from the SMTP settings in your Volanea dashboard.
import os
import smtplib
import ssl
from email.message import EmailMessage
msg = EmailMessage()
msg["Subject"] = "Welcome to Acme"
msg["From"] = "Acme Support <support@your-verified-domain.example>"
msg["To"] = os.environ["VOLANEA_TO"]
# The first body is the plain-text part; add_alternative adds the HTML part
# and turns the message into multipart/alternative.
msg.set_content("Welcome to Acme\n\nYour account is ready.")
msg.add_alternative(
"<h1>Welcome to Acme</h1><p>Your account is ready.</p>",
subtype="html",
)
context = ssl.create_default_context()
with smtplib.SMTP(
os.environ["VOLANEA_SMTP_HOST"],
int(os.environ["VOLANEA_SMTP_PORT"]),
timeout=15,
) as smtp:
smtp.starttls(context=context) # upgrade to TLS before sending credentials
smtp.login("volanea", os.environ["VOLANEA_API_KEY"])
smtp.send_message(msg)
print("Message accepted by the SMTP server.")
This version assumes a port that uses STARTTLS. If your SMTP settings specify implicit TLS instead, replace smtplib.SMTP(...) with smtplib.SMTP_SSL(host, port, context=context) and remove the starttls() call. Over SMTP the Name <address> form in the From header is normal; it is only the JSON API that wants the display name in a separate fromName field.
Add an attachment
Call add_attachment() after the bodies are set. The message becomes multipart/mixed, with the text and HTML alternatives kept together as the first part:
with open("invoice-2041.pdf", "rb") as f:
msg.add_attachment(
f.read(),
maintype="application",
subtype="pdf",
filename="invoice-2041.pdf",
)
On Volanea, a message with an attachment counts as two credits rather than one, whether it is sent over SMTP or the API.
sendmail() versus send_message()
smtplib has two send methods. send_message(msg) takes an EmailMessage and reads the envelope sender and recipients from its headers, which is what you want almost every time. sendmail(from_addr, to_addrs, msg_string) is the older, lower-level call: you pass the envelope addresses and an already-serialized message yourself. It is easy to get the two out of sync, for example by putting a Bcc address in the headers where every recipient can see it. Neither has anything to do with the Unix sendmail program, which smtplib does not use.
Which Python email library should you use?
| Approach | Use it when | Watch out for |
|---|---|---|
requests + REST API (this guide's main example) | New application code, background workers | Add a timeout and an Idempotency-Key for retries |
smtplib + email (standard library) | No dependencies allowed, or existing SMTP code | No idempotency mechanism; you handle TLS mode and connection errors |
Framework mailer (Django's send_mail, Flask extensions) | You are inside that framework already | It is still SMTP or an API underneath; configure it with the same credentials |
Python 2
Python 2 reached end of life on January 1, 2020, and 2.7.18, released in April 2020, was the final version. It gets no security fixes, which matters for code that handles TLS and credentials. The EmailMessage API above is Python 3 only. If a legacy Python 2 script must keep sending email, the practical fix is to upgrade it to Python 3 rather than patch it.
What mailto: does in Python
A mailto: link does not send email. It asks the user's own mail client to open a draft, so it only makes sense on a desktop machine with a person sitting at it, never on a server:
import webbrowser
from urllib.parse import quote
webbrowser.open(
"mailto:support@example.com"
f"?subject={quote('Bug report')}&body={quote('Steps to reproduce:')}"
)
To send email from a backend, script, or scheduled job, use the REST API or smtplib as shown above.
Timeouts, retries, and duplicate sends
The example includes a connection timeout and a read timeout. Without a timeout, a stalled network connection can block a Python worker for an unpredictable period. That can exhaust web-server threads or job-worker capacity under load.
A timeout does not always mean Volanea did not receive the request. The provider may have accepted the message just before the network response was lost. Retrying blindly can therefore create duplicate emails.
Use this sequence for production transactional sends:
- Assign an internal event identifier, such as an order ID plus an event type.
- Store the event and its send state durably before sending.
- Attempt the HTTP request with a bounded timeout.
- Retry only failures that are plausibly transient, such as connection failures, timeouts, or server errors.
- Ensure the retry worker recognizes that the underlying business event has already been processed.
- Record the API result and later reconcile it with delivery events where applicable.
Volanea's send endpoint accepts an Idempotency-Key header for exactly this case. Derive the key from the event identifier in step 1 and send the same key, with the same body, on every retry. A repeat returns the stored response instead of sending a second email, and the response carries an X-Idempotent-Replay: true header. Reusing a key with a different body is rejected with 409 and nothing is sent.
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": f"order-receipt:{order_id}",
}
The idempotency key guide covers how to choose and store keys.
Do not retry every 4xx response. A 400 response often indicates a payload problem, such as a missing required field or invalid address format. A 401 or 403 response generally points to credentials or authorization. Retrying those responses without changing configuration only adds noise and may obscure the real issue.
For 429 responses, slow down according to the response information and your application’s queueing policy. For 5xx responses, retry with exponential backoff and a cap. The important rule is that retries should be aware of the message’s business identity, not merely the HTTP status code.
Test safely before production
Start with an inbox you control. Confirm that the message appears, that its sender is correct, and that the plain-text fallback reads well. Then test with a small set of real mailbox providers your recipients commonly use.
A practical test checklist includes:
- Confirm the script fails clearly when
VOLANEA_API_KEYis absent. - Confirm the sender identity is accepted by your sending configuration.
- Check the email on desktop and mobile mail clients.
- Check the plain-text view, not only the formatted HTML view.
- Verify that links use HTTPS and point to the correct environment.
- Send a deliberately malformed request in a non-production environment to verify error logging.
- Test a temporary network failure to make sure your application does not create uncontrolled retries.
- Confirm monitoring distinguishes API acceptance from downstream delivery or engagement events.
Avoid using a production customer address for first tests unless you have a clear operational reason and the recipient expects the message. A test inbox gives you freedom to revise sender names, HTML, and copy without accidentally confusing a customer.
Common errors
401 Unauthorized or authentication failures
A 401 response usually means the API key is missing, malformed, revoked, or not being sent as expected. First confirm that the environment variable is present in the process that starts Python:
python -c "import os; print(bool(os.getenv('VOLANEA_API_KEY')))"
If this prints False, Python cannot see the variable. Check whether .env is in the working directory, whether load_dotenv() runs before os.getenv(), and whether your deployment platform has the secret configured for the correct service and environment.
Also inspect the authorization header construction. It must include the authentication scheme and a space before the key:
"Authorization": f"Bearer {api_key}"
Do not log the full authorization header or API key while debugging. If you suspect a key was exposed, rotate it and update the deployed secret rather than continuing to use it.
400 Bad Request or validation errors
A 400 response means the service understood the HTTP request but rejected its contents. Print the response body during development because it may describe the invalid field:
print(response.status_code)
print(response.text)
Volanea reports field validation failures as 422 rather than 400, with the failing field described in the response body. Common payload mistakes include an empty subject, an invalid recipient address, a display name inside from (use fromName), missing HTML or text content, or a misspelled field name: the send endpoint rejects unknown fields, so reply_to or cc copied from another provider's API fails instead of being silently ignored. to can be a single address or an array of up to 50.
Do not swallow a 400 and report “email sent” to your application. Make the failure observable and preserve a safe error summary so a developer can repair the message generator.
415 Unsupported Media Type or wrong content type
This error commonly appears when a JSON API receives form data, multipart data, or a body that lacks the expected media type. Send a Python dictionary with json=payload and use this header:
"Content-Type": "application/json"
Avoid this pattern for a JSON request:
requests.post(API_URL, data=payload)
With data=payload, requests encodes the dictionary as form data by default. The endpoint may not parse it as JSON. Use json=payload unless you have a documented reason to send another format.
403 Forbidden or sender authorization errors
A 403 can indicate that the key is valid but lacks permission for the requested operation or that the sender identity is not permitted. Check that you are using the correct environment’s credentials and that the address in VOLANEA_FROM belongs to a configured sending domain.
Do not solve a sender problem by substituting a consumer mailbox address, such as a personal Gmail or Outlook address, into the from field. Use an address on a domain your organization controls and has prepared for sending.
429 Too Many Requests
A 429 response means your application is sending faster than the service currently allows. The right response is to queue work, reduce concurrency, and retry after a controlled delay. Do not create a tight loop around requests.post().
For bursty event streams, put messages in a queue and have a worker consume them at a known rate. This gives you control over ordering, retries, and backpressure. It also prevents a sudden traffic spike from turning into a pile of simultaneous HTTP retries.
Timeouts and connection failures
A requests.exceptions.Timeout can occur during connection establishment or while waiting for a response. A ConnectionError can result from DNS resolution issues, outbound firewall rules, proxy configuration, or a temporary network failure.
The sample handles both errors and exits with a non-zero code. In a web application, translate these exceptions into a retryable job state rather than showing raw infrastructure errors to end users. Remember that a timeout leaves the send result uncertain; design retry behavior with duplicate prevention in mind.
Async and await mistakes
The code in this guide uses requests, which is synchronous. Do not write this:
await requests.post(API_URL, headers=headers, json=payload)
requests.post() returns a normal response object, not an awaitable coroutine. Python will raise an error if you try to await it.
If your application is asynchronous, such as an ASGI service, either run a synchronous client safely outside the event loop or use an async-capable HTTP library and follow that library’s documented request syntax. Do not mix sync and async styles casually: calling blocking requests.post() directly inside a high-concurrency async endpoint can block the event loop and degrade unrelated requests.
ModuleNotFoundError: No module named 'requests'
This means the Python interpreter running the script cannot find the installed package. Activate the intended virtual environment and install packages through that interpreter:
python -m pip install requests python-dotenv
python send_email.py
If the issue continues, compare which python with which pip on macOS or Linux, or use python -m pip exclusively. On Windows, verify that the active virtual environment is the one from which the script is being executed.
Deliverability considerations for transactional email
A successful API call is only the start of reliable email delivery. Transactional messages should have a clear purpose, expected timing, and trustworthy sender identity.
Use stable sender domains and recognizable display names. A password-reset request should arrive promptly and identify the product that initiated it. A receipt should contain the purchase information a customer expects. A sudden change in sender identity, inconsistent branding, or a message that arrives long after the triggering action can make even legitimate email look suspicious.
Keep transactional content focused. A receipt can include an appropriate account-management link, but it should not become a broad promotional newsletter. Separating operational and marketing intent improves customer expectations and makes it easier for your application to apply the right consent and suppression rules.
Make the email useful without requiring images or complex CSS to load. Put essential information in text and HTML, use descriptive links, and ensure the message remains understandable when images are disabled. For security-sensitive messages, avoid including secrets directly in the body or subject; use time-limited, single-purpose links where your product design supports them.
Next steps
Once your first Python send is working, expand the integration in two directions.
First, add webhooks. Webhooks allow your application to receive event notifications after a message is accepted, delivered, bounced, complained about, or otherwise processed. Build a small HTTPS endpoint that validates incoming webhook requests, records events idempotently, and updates your application’s delivery state. Do not assume one webhook event will arrive only once or in perfect chronological order; event handlers should tolerate retries and duplicates.
Second, introduce templates. Templates let your team keep a consistent structure for recurring messages such as receipts, invitation emails, and account notifications. Whether you render HTML in Python or use provider-side template capabilities available in your account, keep variables explicit, validate required fields, escape untrusted values, and maintain a text alternative. A template system should reduce repeated markup without making message behavior opaque.
As your volume grows, add a durable outbox or queue, structured logs with safe request identifiers, alerting for elevated failures, and tests for your most important email flows. These controls turn a working send call into dependable messaging infrastructure.
FAQ
Do I need a Python-specific Volanea SDK to send email with Python?
No. A standard HTTPS client is sufficient for a REST integration. This guide uses requests to send a JSON payload with a bearer API key, so the code does not depend on a provider-specific Python SDK method.
Should I put my Volanea API key in the Python source file?
No. Load it from an environment variable or a deployment secret manager. Keep .env files out of version control and never expose the key in frontend code, screenshots, logs, or support tickets.
Does a successful API response mean the recipient received the message?
It means the service accepted the request for processing. Delivery, bounces, complaints, and engagement are later outcomes. Use webhook events and application monitoring to track those downstream states.
Why should I include a plain-text email body?
Plain text provides a readable fallback for clients or settings that do not render HTML. It also improves accessibility and ensures the essential information remains available without formatting.
Can I use this code in an async Python application?
The example is synchronous because it uses requests. For an async application, do not await requests.post(). Use an async HTTP client according to its documentation or isolate the synchronous request from the event loop.
Can I send email with Python without any library?
Yes. The standard library's email module builds the message and smtplib sends it over SMTP, so nothing needs installing. You still need an SMTP server to send through and credentials for it; for Volanea that is the username volanea with your secret API key as the password.
Can I send email from Python without credentials or a paid service?
Not to real inboxes. Any service that delivers mail on your behalf needs some credential, otherwise anyone could send as your domain. Volanea's Free plan gives 1,000 credits a month with no card required, and a key starting with sk_test_ lets you run the code above without delivering anything to a real recipient.
How do I send email with Python 2?
Python 2 reached end of life on January 1, 2020 and no longer receives security fixes. The modern email.message.EmailMessage API used in this guide is Python 3 only. Upgrade the script to Python 3 rather than building new email code on Python 2.
How do I test my Python email code without emailing customers?
Send to inboxes you control, use a test-mode API key while developing, and check the plain-text part as well as the HTML. The email testing guide covers render checks, spam checks, and automated tests in more depth.