Elastic Email Python SDK

The official Python client library for the Elastic Email REST API v4.

Installation • Quick start • Examples • API reference • Models • Contributing

---

Features

• Transactional and bulk email. Send single messages, bulk campaigns or CSV merge-file sends.
• Contacts, lists and segments. Add, update, import, export and bulk-delete contacts.
• Campaigns and automations. Create, update, pause and trigger automations for a contact.
• Templates, files and attachments. Manage templates and uploaded files.
• Domains. Verify sending domains and check SPF, DKIM, tracking and certificate status.
• Webhooks and inbound routes. Receive delivery events and route incoming mail.
• Statistics, events and suppressions. Track delivery, bounces, complaints and unsubscribes.
• Subaccounts and security. Manage subaccounts and API keys.
• Typed models. Request and response models are Pydantic v2 classes, and the package ships type hints (py.typed).

Requirements

Dependency	Version
Python	3.8 or later
urllib3	1.25.3 or later, below 3.0
python-dateutil	2.8.2 or later
pydantic	2.x
typing-extensions	4.7.1 or later

You'll also need an Elastic Email API key. You can create one in your API settings. Each endpoint's documentation lists the access level it needs.

Installation

Install the ElasticEmail package from PyPI:

pip install ElasticEmail

Or with Poetry or uv:

poetry add ElasticEmail
uv add ElasticEmail

Then import the package:

import ElasticEmail

Quick start

Important

Elastic Email only sends from verified domains. Before your first send, verify your sending domain and use an address on that domain as the sender.

Configure the client

import os

import ElasticEmail
from ElasticEmail.rest import ApiException
from ElasticEmail.models import (
    BodyContentType,
    BodyPart,
    EmailContent,
    EmailTransactionalMessageData,
    TransactionalRecipient,
)

configuration = ElasticEmail.Configuration(host="https://api.elasticemail.com/v4")
configuration.api_key["apikey"] = os.environ["ELASTICEMAIL_API_KEY"]

Tip

Keep your API key out of source code. Load it from an environment variable, a .env file that isn't committed, or a secrets manager.

Send a transactional email

message = EmailTransactionalMessageData(
    recipients=TransactionalRecipient(to=["john.doe@example.com"]),
    content=EmailContent(
        var_from="My App <no-reply@yourdomain.com>",
        subject="Welcome aboard!",
        body=[
            BodyPart(content_type=BodyContentType.HTML, content="<h1>Hello!</h1><p>Thanks for signing up.</p>"),
            BodyPart(content_type=BodyContentType.PLAINTEXT, content="Hello! Thanks for signing up."),
        ],
    ),
)

with ElasticEmail.ApiClient(configuration) as api_client:
    emails = ElasticEmail.EmailsApi(api_client)
    try:
        result = emails.emails_transactional_post(message)
        print(f"Sent. TransactionID: {result.transaction_id}, MessageID: {result.message_id}")
    except ApiException as e:
        print(f"Elastic Email API error {e.status}: {e.body}")

The sender field is var_from because from is a reserved word in Python. The address must use a domain you've verified in your Elastic Email account.

Send from a template with merge fields

message = EmailTransactionalMessageData(
    recipients=TransactionalRecipient(to=["john.doe@example.com"]),
    content=EmailContent(
        var_from="My App <no-reply@yourdomain.com>",
        template_name="welcome-template",
        merge={"firstname": "John"},
    ),
)

with ElasticEmail.ApiClient(configuration) as api_client:
    ElasticEmail.EmailsApi(api_client).emails_transactional_post(message)

Proxy, timeouts and retries

configuration.proxy = "http://myProxyUrl:80/"
configuration.retries = 3

# Per-request timeout in seconds, or a (connect, read) tuple
emails.emails_transactional_post(message, _request_timeout=(5, 30))

More examples

More complete, runnable samples are in the Elastic Email examples repository. It covers transactional email, SMTP, webhooks, inbound email, contacts and serverless platforms across 20+ languages and frameworks.

• 🐍 Python examples
• 📂 All examples

Snippets in this repository

Function
addCampaign	readme
addContacts	readme
addList	readme
addTemplate	readme
deleteCampaign	readme
deleteContacts	readme
deleteList	readme
deleteTemplate	readme
exportContacts	readme
loadCampaign	readme
loadCampaignsStats	readme
loadChannelsStats	readme
loadList	readme
loadStatistics	readme
loadTemplate	readme
sendBulkEmails	readme
sendTransactionalEmails	readme
updateCampaign	readme
uploadContacts	readme

Authentication

Scheme	Header	Used for
apikey	X-ElasticEmail-ApiKey	All standard API calls
ApiKeyAuthCustomBranding	X-Auth-Token	Custom-branding (white-label) accounts

API limits

• Up to 20 concurrent connections per account
• A hard timeout of 600 seconds per request

API reference

All URIs are relative to https://api.elasticemail.com/v4. The SDK covers 114 endpoints across 16 API classes: CampaignsApi, ContactsApi, DomainsApi, EmailsApi, EventsApi, FilesApi, InboundRouteApi, ListsApi, SecurityApi, SegmentsApi, StatisticsApi, SubAccountsApi, SuppressionsApi, TemplatesApi, VerificationsApi and WebhookApi.

Show all endpoints

All URIs are relative to https://api.elasticemail.com/v4

Class	Method	HTTP request	Description
CampaignsApi	campaigns_automation_by_name_trigger_post	POST /campaigns/automation/{name}/trigger	Trigger Automation for Contact
CampaignsApi	campaigns_by_name_delete	DELETE /campaigns/{name}	Delete Campaign
CampaignsApi	campaigns_by_name_get	GET /campaigns/{name}	Load Campaign
CampaignsApi	campaigns_by_name_pause_put	PUT /campaigns/{name}/pause	Pause Campaign
CampaignsApi	campaigns_by_name_put	PUT /campaigns/{name}	Update Campaign
CampaignsApi	campaigns_get	GET /campaigns	Load Campaigns
CampaignsApi	campaigns_post	POST /campaigns	Add Campaign
ContactsApi	contacts_by_email_delete	DELETE /contacts/{email}	Delete Contact
ContactsApi	contacts_by_email_get	GET /contacts/{email}	Load Contact
ContactsApi	contacts_by_email_put	PUT /contacts/{email}	Update Contact
ContactsApi	contacts_delete_post	POST /contacts/delete	Delete Contacts Bulk
ContactsApi	contacts_export_by_id_status_get	GET /contacts/export/{id}/status	Check Export Status
ContactsApi	contacts_export_post	POST /contacts/export	Export Contacts
ContactsApi	contacts_get	GET /contacts	Load Contacts
ContactsApi	contacts_import_post	POST /contacts/import	Upload Contacts
ContactsApi	contacts_post	POST /contacts	Add Contact
DomainsApi	domains_by_domain_delete	DELETE /domains/{domain}	Delete Domain
DomainsApi	domains_by_domain_get	GET /domains/{domain}	Load Domain
DomainsApi	domains_by_domain_put	PUT /domains/{domain}	Update Domain
DomainsApi	domains_by_domain_restricted_get	GET /domains/{domain}/restricted	Check for domain restriction
DomainsApi	domains_by_domain_verification_put	PUT /domains/{domain}/verification	Verify Domain
DomainsApi	domains_by_email_default_patch	PATCH /domains/{email}/default	Set Default
DomainsApi	domains_get	GET /domains	Load Domains
DomainsApi	domains_post	POST /domains	Add Domain
EmailsApi	emails_by_msgid_view_get	GET /emails/{msgid}/view	View Email
EmailsApi	emails_by_transactionid_status_get	GET /emails/{transactionid}/status	Get Status
EmailsApi	emails_mergefile_post	POST /emails/mergefile	Send Bulk Emails CSV
EmailsApi	emails_post	POST /emails	Send Bulk Emails
EmailsApi	emails_transactional_post	POST /emails/transactional	Send Transactional Email
EventsApi	events_by_transactionid_get	GET /events/{transactionid}	Load Email Events
EventsApi	events_channels_by_name_export_post	POST /events/channels/{name}/export	Export Channel Events
EventsApi	events_channels_by_name_get	GET /events/channels/{name}	Load Channel Events
EventsApi	events_channels_export_by_id_status_get	GET /events/channels/export/{id}/status	Check Channel Export Status
EventsApi	events_export_by_id_status_get	GET /events/export/{id}/status	Check Export Status
EventsApi	events_export_post	POST /events/export	Export Events
EventsApi	events_get	GET /events	Load Events
FilesApi	files_by_name_delete	DELETE /files/{name}	Delete File
FilesApi	files_by_name_get	GET /files/{name}	Download File
FilesApi	files_by_name_info_get	GET /files/{name}/info	Load File Details
FilesApi	files_get	GET /files	List Files
FilesApi	files_post	POST /files	Upload File
InboundRouteApi	inboundroute_by_id_delete	DELETE /inboundroute/{id}	Delete Route
InboundRouteApi	inboundroute_by_id_get	GET /inboundroute/{id}	Get Route
InboundRouteApi	inboundroute_by_id_put	PUT /inboundroute/{id}	Update Route
InboundRouteApi	inboundroute_get	GET /inboundroute	Get Routes
InboundRouteApi	inboundroute_order_put	PUT /inboundroute/order	Update Sorting
InboundRouteApi	inboundroute_post	POST /inboundroute	Create Route
ListsApi	lists_by_listname_contacts_get	GET /lists/{listname}/contacts	Load Contacts in List
ListsApi	lists_by_name_contacts_post	POST /lists/{name}/contacts	Add Contacts to List
ListsApi	lists_by_name_contacts_remove_post	POST /lists/{name}/contacts/remove	Remove Contacts from List
ListsApi	lists_by_name_delete	DELETE /lists/{name}	Delete List
ListsApi	lists_by_name_get	GET /lists/{name}	Load List
ListsApi	lists_by_name_put	PUT /lists/{name}	Update List
ListsApi	lists_get	GET /lists	Load Lists
ListsApi	lists_post	POST /lists	Add List
SecurityApi	security_apikeys_by_name_delete	DELETE /security/apikeys/{name}	Delete ApiKey
SecurityApi	security_apikeys_by_name_get	GET /security/apikeys/{name}	Load ApiKey
SecurityApi	security_apikeys_by_name_put	PUT /security/apikeys/{name}	Update ApiKey
SecurityApi	security_apikeys_get	GET /security/apikeys	List ApiKeys
SecurityApi	security_apikeys_post	POST /security/apikeys	Add ApiKey
SecurityApi	security_smtp_by_name_delete	DELETE /security/smtp/{name}	Delete SMTP Credential
SecurityApi	security_smtp_by_name_get	GET /security/smtp/{name}	Load SMTP Credential
SecurityApi	security_smtp_by_name_put	PUT /security/smtp/{name}	Update SMTP Credential
SecurityApi	security_smtp_get	GET /security/smtp	List SMTP Credentials
SecurityApi	security_smtp_post	POST /security/smtp	Add SMTP Credential
SegmentsApi	segments_by_name_delete	DELETE /segments/{name}	Delete Segment
SegmentsApi	segments_by_name_get	GET /segments/{name}	Load Segment
SegmentsApi	segments_by_name_put	PUT /segments/{name}	Update Segment
SegmentsApi	segments_get	GET /segments	Load Segments
SegmentsApi	segments_post	POST /segments	Add Segment
StatisticsApi	statistics_campaigns_by_name_get	GET /statistics/campaigns/{name}	Load Campaign Stats
StatisticsApi	statistics_campaigns_get	GET /statistics/campaigns	Load Campaigns Stats
StatisticsApi	statistics_channels_by_name_get	GET /statistics/channels/{name}	Load Channel Stats
StatisticsApi	statistics_channels_get	GET /statistics/channels	Load Channels Stats
StatisticsApi	statistics_get	GET /statistics	Load Statistics
SubAccountsApi	subaccounts_by_email_apikey_get	GET /subaccounts/{email}/apikey	Get SubAccount ApiKey
SubAccountsApi	subaccounts_by_email_credits_patch	PATCH /subaccounts/{email}/credits	Add, Subtract Email Credits
SubAccountsApi	subaccounts_by_email_delete	DELETE /subaccounts/{email}	Delete SubAccount
SubAccountsApi	subaccounts_by_email_get	GET /subaccounts/{email}	Load SubAccount
SubAccountsApi	subaccounts_by_email_settings_email_put	PUT /subaccounts/{email}/settings/email	Update SubAccount Email Settings
SubAccountsApi	subaccounts_get	GET /subaccounts	Load SubAccounts
SubAccountsApi	subaccounts_post	POST /subaccounts	Add SubAccount
SuppressionsApi	suppressions_bounces_get	GET /suppressions/bounces	Get Bounce List
SuppressionsApi	suppressions_bounces_import_post	POST /suppressions/bounces/import	Add Bounces Async
SuppressionsApi	suppressions_bounces_post	POST /suppressions/bounces	Add Bounces
SuppressionsApi	suppressions_by_email_delete	DELETE /suppressions/{email}	Delete Suppression
SuppressionsApi	suppressions_by_email_get	GET /suppressions/{email}	Get Suppression
SuppressionsApi	suppressions_complaints_get	GET /suppressions/complaints	Get Complaints List
SuppressionsApi	suppressions_complaints_import_post	POST /suppressions/complaints/import	Add Complaints Async
SuppressionsApi	suppressions_complaints_post	POST /suppressions/complaints	Add Complaints
SuppressionsApi	suppressions_get	GET /suppressions	Get Suppressions
SuppressionsApi	suppressions_unsubscribes_get	GET /suppressions/unsubscribes	Get Unsubscribes List
SuppressionsApi	suppressions_unsubscribes_import_post	POST /suppressions/unsubscribes/import	Add Unsubscribes Async
SuppressionsApi	suppressions_unsubscribes_post	POST /suppressions/unsubscribes	Add Unsubscribes
TemplatesApi	templates_by_name_delete	DELETE /templates/{name}	Delete Template
TemplatesApi	templates_by_name_get	GET /templates/{name}	Load Template
TemplatesApi	templates_by_name_put	PUT /templates/{name}	Update Template
TemplatesApi	templates_get	GET /templates	Load Templates
TemplatesApi	templates_post	POST /templates	Add Template
VerificationsApi	verifications_by_email_delete	DELETE /verifications/{email}	Delete Email Verification Result
VerificationsApi	verifications_by_email_get	GET /verifications/{email}	Get Email Verification Result
VerificationsApi	verifications_by_email_post	POST /verifications/{email}	Verify Email
VerificationsApi	verifications_files_by_id_delete	DELETE /verifications/files/{id}	Delete File Verification Result
VerificationsApi	verifications_files_by_id_result_download_get	GET /verifications/files/{id}/result/download	Download File Verification Result
VerificationsApi	verifications_files_by_id_result_get	GET /verifications/files/{id}/result	Get Detailed File Verification Result
VerificationsApi	verifications_files_by_id_verification_post	POST /verifications/files/{id}/verification	Start verification
VerificationsApi	verifications_files_post	POST /verifications/files	Upload File with Emails
VerificationsApi	verifications_files_result_get	GET /verifications/files/result	Get Files Verification Results
VerificationsApi	verifications_get	GET /verifications	Get Emails Verification Results
WebhookApi	webhook_by_publicid_delete	DELETE /webhook/{publicid}	Delete Webhook
WebhookApi	webhook_by_publicid_get	GET /webhook/{publicid}	Load Webhook
WebhookApi	webhook_by_publicid_put	PUT /webhook/{publicid}	Update Webhook
WebhookApi	webhook_get	GET /webhook	Load Webhooks
WebhookApi	webhook_post	POST /webhook	Add Webhook

Models

Show all 98 models

• AccessLevel
• AccountStatusEnum
• ApiKey
• ApiKeyPayload
• BodyContentType
• BodyPart
• Campaign
• CampaignOptions
• CampaignRecipient
• CampaignStatus
• CampaignTemplate
• CertificateValidationStatus
• ChannelLogStatusSummary
• CompressionFormat
• ConsentData
• ConsentTracking
• Contact
• ContactActivity
• ContactPayload
• ContactSource
• ContactStatus
• ContactUpdatePayload
• ContactsList
• DKIMRecord
• DeliveryOptimizationType
• DomainData
• DomainDetail
• DomainOwner
• DomainPayload
• DomainUpdatePayload
• EmailContent
• EmailData
• EmailJobFailedStatus
• EmailJobStatus
• EmailMessageData
• EmailPredictedValidationStatus
• EmailRecipient
• EmailSend
• EmailStatus
• EmailTransactionalMessageData
• EmailValidationResult
• EmailValidationStatus
• EmailView
• EmailsPayload
• EncodingType
• EventType
• EventsOrderBy
• ExportFileFormats
• ExportLink
• ExportStatus
• FileInfo
• FilePayload
• FileUploadResult
• InboundPayload
• InboundRoute
• InboundRouteActionType
• InboundRouteFilterType
• ListPayload
• ListUpdatePayload
• LogJobStatus
• LogStatusSummary
• MergeEmailPayload
• MessageAttachment
• MessageCategory
• MessageCategoryEnum
• NewApiKey
• NewSmtpCredentials
• Options
• RecipientEvent
• Segment
• SegmentPayload
• SmtpCredentials
• SmtpCredentialsPayload
• SortOrderItem
• SplitOptimizationType
• SplitOptions
• SubAccountInfo
• SubaccountEmailCreditsPayload
• SubaccountEmailSettings
• SubaccountEmailSettingsPayload
• SubaccountPayload
• SubaccountSettingsInfo
• SubaccountSettingsInfoPayload
• Suppression
• Template
• TemplatePayload
• TemplateScope
• TemplateType
• TrackingType
• TrackingValidationStatus
• TransactionalRecipient
• Utm
• VerificationFileResult
• VerificationFileResultDetails
• VerificationStatus
• Webhook
• WebhookCreatePayload
• WebhookUpdatePayload

Tests

pip install -r requirements.txt -r test-requirements.txt
pytest

Versioning

The SDK follows the Elastic Email API v4. Package versions and release notes are listed on PyPI and in GitHub Releases.

Build details

• API version: 4.0.0
• SDK version: 4.2.1
• Generator version: 7.11.0
• Build package: org.openapitools.codegen.languages.PythonClientCodegen

Contributing

Contributions are welcome! Most of this SDK is generated from the Elastic Email OpenAPI specification, so please read CONTRIBUTING.md before opening a pull request.

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue

This project follows the Contributor Covenant Code of Conduct.

Support

Important

The fastest way to get help is the chat widget on elasticemail.com. Our support team can help with your account, sending, deliverability and API questions.

• 💬 Chat with support on elasticemail.com (preferred)
• 📚 API documentation
• 🧪 Examples repository
• 🐛 GitHub issues, for bugs in this SDK only

License

Released under the MIT License. Copyright © 2021–2026 Elastic Email.