Usage

To use django-db-mailer on the your project - Add and Configure mail templates on the admin page.

High level API

Send mail API with comments for all available options:

from dbmail import send_db_mail

send_db_mail(
    # slug - which defined on db template
    slug='welcome',

    # recipient can be list, or str separated with comma or simple string
    # 'user1@example.com' or 'user1@example.com, user2@example.com' or
    # ['user1@example.com', 'user2@example.com'] or string Mail group slug
    recipient='user1@example.com',

    # All *args params will be accessible on template context
    {
        'username': request.user.username,
        'full_name': request.user.get_full_name(),
        'signup_date': request.user.date_joined
    },

    # You can access to all model fields. For m2m and fk fields, you should use module_name
    MyModel.objects.get(pk=1),

    #######################################################################
    ### Optional kwargs:
    #######################################################################
    from_email='from@example.com',
    cc=['cc@example.com'],
    bcc=['bcc_1@example.com', 'bcc_2@example.com'],

    # For store on mail logs
    user=User.objects.get(pk=1),

    # Current language code, which selected by user
    language='ru',

    # This options is documented on the Django docs
    attachments=[(filename, content, mimetype)],
    files=['hello.jpg', 'world.png'],
    headers={'Custom-Header':'Some value'},

    # For working with different queue, you can specify queue name on the settings, or on option
    queue='default',

    # Time for retry failed send. Working with celery only
    retry_delay=300,

    # Max retries, when sending is failed
    max_retries=3,

    # You can disable retry function
    retry=True,

    # Hard limit on seconds
    time_limit=30,

    # Postpone send email for specified seconds
    send_after=60,

    # You can disable celery for debug messages, or when error is occurred,
    # and email can not be delivered by celery.
    # Or some part of your app run on instance, where celery is not used.
    use_celery=True,
)

For track information about read - add dbmail into urls.

SMS API

from dbmail import send_db_sms


send_db_sms(
    # slug which defined on db template
    slug='welcome',

    # recipient can be list, or str separated with comma or simple string
    # '+79031234567' or '+79031234567, +79031234568, +79031234569' or
    # ['+79031234567', '+79031234568'] or string Mail group slug
    recipient='+79031234567',

    # All *args params will be accessible on template context
    {
        'username': request.user.username,
        'full_name': request.user.get_full_name(),
        'signup_date': request.user.date_joined
    },

    # You can access to all model fields. For m2m and fk fields, you should use module_name
    MyModel.objects.get(pk=1),

    # Optional kwargs:
    # from_email='DBMail'
    # user=User.objects.get(pk=1),
    #
    # language='ru',
    #
    # queue='default',
    # retry_delay=300,
    # max_retries=3,
    # retry=True,
    # time_limit=30,
    # send_after=60,
    #
    # use_celery=True,
)

TTS API

from dbmail import send_db_tts


send_db_tts(
    # slug which defined on db template
    slug='welcome',

    # recipient can be list, or str separated with comma or simple string
    # '+79031234567' or '+79031234567, +79031234568, +79031234569' or
    # ['+79031234567', '+79031234568'] or string Mail group slug
    recipient='+79031234567',

    # All *args params will be accessible on template context
    {
        'username': request.user.username,
        'full_name': request.user.get_full_name(),
        'signup_date': request.user.date_joined
    },

    # You can access to all model fields. For m2m and fk fields, you should use module_name
    MyModel.objects.get(pk=1),

    # Optional kwargs:
    # from_email='DBMail'
    # user=User.objects.get(pk=1),
    #
    # language='ru',
    #
    # queue='default',
    # retry_delay=300,
    # max_retries=3,
    # retry=True,
    # time_limit=30,
    # send_after=60,
    #
    # use_celery=True,
)

Text to speech supported by default provider. But maybe not supported by your provider.

PUSH API

from dbmail import send_db_push


send_db_push(
    # slug which defined on db template
    slug='welcome',

    # recipient can be list, or str separated with comma or simple string
    # '+34cc3e5f0d2abf2ca0f9af170bd8cd2372a22f8a' or '34cc3e5f0d2abf2ca0f9af170bd8cd2372a22f8a, 34cc3e5f0d2abf2ca0f9af170bd8cd2372a22f8b' or
    # ['34cc3e5f0d2abf2ca0f9af170bd8cd2372a22f8a', '34cc3e5f0d2abf2ca0f9af170bd8cd2372a22f8b'] or string Mail group slug
    recipient='34cc3e5f0d2abf2ca0f9af170bd8cd2372a22f8c',

    # All *args params will be accessible on template context
    {
        'username': request.user.username,
        'full_name': request.user.get_full_name(),
        'signup_date': request.user.date_joined
    },

    # You can access to all model fields. For m2m and fk fields, you should use module_name
    MyModel.objects.get(pk=1),

    # Optional kwargs:
    # backend='dbmail.backends.push',
    # event='Server is down!',
    # from_email='ConsoleApp'
    # user=User.objects.get(pk=1),
    #
    # language='ru',
    #
    # queue='default',
    # retry_delay=300,
    # max_retries=3,
    # retry=True,
    # time_limit=30,
    # send_after=60,
    #
    # use_celery=True,
)

DBMail Backends

By default django-dbmail used 4 built-in backends (Mail/Sms/Tts/Push). But nothing prevents to write your own backend to work with all that you want.

Web API

You can use this app with different languages. For example on mobile apps, bash or some part of another languages without smtp access for notification & etc.

At first create API key for your app (you can do it from browser):

from dbmail.models import ApiKey

ApiKey.objects.create(name='Test', api_key='ZzriUzE')

Add urls route:

# urls.py
urlpatterns += patterns(
    '', url(r'^dbmail/', include('dbmail.urls')),
)

And send email from bash using curl:

$ apt-get install curl || brew install curl
$ curl -X POST http://127.0.0.1:8000/dbmail/api/ --data 'api_key=ZzriUzE&slug=welcome&recipient=root@local.host'

or sms:

curl -X POST http://127.0.0.1:8000/dbmail/api/ –data ‘api_key=ZzriUzE&slug=welcome&recipient=%2B79031234567&backend=sms’

API bandwidth is 1k+ rps on i7 2.3GHz

DB template

Simple example to create template from the shell:

from dbmail.models import MailTemplate

# Create new dbmail template.
MailTemplate.objects.create(
    name="Site welcome template",
    subject="Welcome",
    message="Welcome to our site. We are glad to see you.",
    slug="welcome",
    is_html=False,
)

Subscription api

Full stack (multiple) notification example for django.contrib.auth.models.users

from dbmail.models import MailSubscription
from dbmail import send_db_subscription

# Email notification
MailSubscription.objects.create(
    user_id=1,
    backend="dbmail.backends.mail",
    is_checked=True,
    address="user1@example.com"
)

# Push notification
MailSubscription.objects.create(
    user_id=1,
    backend="dbmail.backends.push",
    start_hour="08:00",
    end_hour="20:00",
    is_checked=True,
    defer_at_allowed_hours=True,
    address="d30NSrq10aO0hsyHDZ3"
)

# Send notification to all devices
send_db_subscription('welcome', 1)

If you want send notification for all subscribers, you can omit user_id

from dbmail.models import MailSubscription
from dbmail import send_db_subscription

# Email notification
MailSubscription.objects.create(
    is_checked=True,
    address="user2@example.com"
)

# Push notification
MailSubscription.objects.create(
    backend="dbmail.backends.push",
    is_checked=True,
    address="d30NSrq10aO0hsyHDZ4"
)

# Send notification to all available user (all devices)
send_db_subscription('welcome')

For all active users which registered at last 3 days ago (all devices):

from datetime import datetime, timedelta
from dbmail import send_db_subscription

send_db_subscription('welcome', None, {
    'user__is_active': 1,
    'user__date_joined__gte': datetime.now() - timedelta(days=3)
})