jwodder / outgoing-mailgun

outgoing extension for Mailgun

GitHub | PyPI | Issues | Changelog

outgoing-mailgun is an extension for outgoing that adds the ability to send e-mails via Mailgun. Simply install outgoing-mailgun alongside outgoing, and you'll be able to specify "mailgun" as a sending method in your outgoing configuration.

Installation

outgoing-mailgun requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install outgoing-mailgun and its dependencies (including outgoing):

python3 -m pip install outgoing-mailgun

Configuration

When using "mailgun" as the sending method in an outgoing configuration, the following configuration fields are recognized:

base-url : HTTP URL (optional)

The base URL to use for Mailgun API requests. This should be either "https://api.mailgun.net" (the default) for domains in Mailgun's US region or "https://api.eu.mailgun.net" for domains in Mailgun's EU region. Trailing slashes on the URL are optional.

domain : string (required)

The domain name you registered with Mailgun for sending e-mail

api-key : password (required)

A Mailgun API key for your domain; see the outgoing documentation on passwords for ways to write this field.

When using the keyring password scheme or another scheme that takes optional host/service and username fields, if the service and/or username is not supplied in the password specifier, then the service defaults to the domain name of the base-url field, and the username defaults to the value of the domain field.

tags : list of strings (optional)

A set of tags to apply to sent e-mails

deliverytime : datetime (optional)

Desired time of delivery for sent e-mails; if no timezone offset is given, it is assumed to be in the local system timezone

dkim : boolean (optional)

Enable/disable DKIM signatures on sent e-mails

testmode : boolean (optional)

Whether to send in test mode

tracking : boolean (optional)

Whether to enable message tracking

tracking-clicks : boolean or "htmlonly" (optional)

Whether to enable clicks tracking in e-mails

tracking-opens : boolean (optional)

Whether to enable opens tracking in e-mails

headers : table with string values (optional)

A collection of custom MIME headers to append to sent e-mails

variables : table with string values (optional)

A collection of Mailgun variables to attach to sent e-mails

Example Configuration

[outgoing]
method = "mailgun"
domain = "mydomain.nil"
api-key = { file = "~/secrets/mailgun.key" }
dkim = true
tags = [ "sent-with-outgoing", "my-campaign" ]
tracking-clicks = "htmlonly"
headers = { Reply-To = "[email protected]" }
variables = { sender = "outgoing", foo = "bar" }

Sender-Specific Behavior

The MailgunSender class provided by this extension is a reentrant and reusable context manager, and its send() method can be called outside of a context. In addition, on success, the send() method returns the message ID of the newly-sent e-mail (without enclosing angle brackets).

outgoing-mailgun's Issues

Should the send() method take an optional deliverytime argument?

On the one hand, deliverytime makes the least sense as a configuration field; it's more something you'd want to send on a per-message basis. On the other hand, adding arguments to certain senders' send() methods breaks the uniformity of the interface; a user would only be able to use a deliverytime argument if they deliberately checked that the sender object was a MailgunSender. On the other other hand, interface uniformity has already taken a bit of a hit from the fact that certain sender objects are reusable, reentrant context managers and can even be used outside of an explicit context, despite the Sender protocol not guaranteeing any of this.