dm_mail Module

Module for sending plain-text e-mails via SMTP, using libcurl.

To send an e-mail, create an SMTP server configuration and a mail type first:

integer                :: rc
type(mail_type)        :: mail
type(mail_server_type) :: server
type(person_type)      :: from, to(1)

! Initialise SMTP backend and set SMTP server details.
rc = dm_mail_init()
rc = dm_mail_create(server, 'example.com', 'username', 'password')

! Create sender, receiver, and e-mail.
from  = person_type(mail='alice@example.com')
to(1) = person_type(mail='bob@example.com')

rc = dm_mail_create(mail, from=from, to=to, subject='Subject', message='Message')

! Send e-mail and finalise SMTP backend.
rc = dm_mail_send(mail, server)
call dm_mail_shutdown()

The procedure dm_mail_init() has to be called once per process, and only if neither the RPC nor the MQTT backend is initialised already.


Uses

  • module~~dm_mail~~UsesGraph module~dm_mail dm_mail curl curl module~dm_mail->curl iso_c_binding iso_c_binding module~dm_mail->iso_c_binding module~dm_error dm_error module~dm_mail->module~dm_error module~dm_kind dm_kind module~dm_mail->module~dm_kind module~dm_person dm_person module~dm_mail->module~dm_person module~dm_time dm_time module~dm_mail->module~dm_time module~dm_util dm_util module~dm_mail->module~dm_util module~dm_error->module~dm_kind module~dm_ascii dm_ascii module~dm_error->module~dm_ascii iso_fortran_env iso_fortran_env module~dm_kind->iso_fortran_env module~dm_time->module~dm_error module~dm_time->module~dm_kind module~dm_time->module~dm_util module~dm_util->module~dm_error module~dm_util->module~dm_kind

Used by

  • module~~dm_mail~~UsedByGraph module~dm_mail dm_mail module~dmpack dmpack module~dmpack->module~dm_mail

Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: MAIL_PLAIN = 0

No transport-layer security.
integer, public, parameter :: MAIL_SSL = 1

Explicit SSL.
integer, public, parameter :: MAIL_TLS = 2

Implicit TLS (StartTLS).

Interfaces

public interface dm_mail_address

Generic function that returns formatted addresses.

  • private pure function mail_address_person(person) result(str)

    Returns e-mail address as allocatable string in the form <address> or "name" <address>, depending on whether the person has a name.

    Arguments

    Type IntentOptional Attributes Name
    type(person_type), intent(in) :: person

    Person type.

    Return Value character(len=:), allocatable

    Address string.

  • private pure function mail_address_persons(persons) result(str)

    Returns list of e-mail addresses in allocatable string.

    Arguments

    Type IntentOptional Attributes Name
    type(person_type), intent(in) :: persons(:)

    Array of person types.

    Return Value character(len=:), allocatable

    List of addresses.

public interface dm_mail_create

Generic function to create mail or server data type.

  • public function dm_mail_create_mail(mail, from, to, subject, message, cc, bcc) result(rc)

    Creates new mail type and inserts passed values. The function return E_INVALID if given arguments are invalid or incomplete.

    Arguments

    Type IntentOptional Attributes Name
    type(mail_type), intent(out) :: mail

    Mail type.
    type(person_type), intent(in) :: from

    Mail sender.
    type(person_type), intent(in) :: to(:)

    Mail recipients.
    character(len=*), intent(in) :: subject

    Mail subject.
    character(len=*), intent(in) :: message

    Mail message.
    type(person_type), intent(in), optional :: cc(:)

    Mail CC recipients.
    type(person_type), intent(in), optional :: bcc(:)

    Mail BCC recipients.

    Return Value integer

  • public function dm_mail_create_server(server, host, username, password, port, tls, timeout, connect_timeout, verify_ssl) result(rc)

    Returns SMTP server type. Argument tls may be one of the following:

    • MAIL_PLAIN – No transport-layer security.
    • MAIL_SSL – Explicit SSL.
    • MAIL_TLS – Implicit TLS (StartTLS).

    Parameter MAIL_PLAIN is used by default. The function returns E_INVALID on error.

    Arguments

    Type IntentOptional Attributes Name
    type(mail_server_type), intent(out) :: server

    Mail server type.
    character(len=*), intent(in) :: host

    SMTP server host.
    character(len=*), intent(in) :: username

    SMTP user name.
    character(len=*), intent(in) :: password

    SMTP password.
    integer, intent(in), optional :: port

    SMTP server port (or 0).
    integer, intent(in), optional :: tls

    SMTP transport-layer security.
    integer, intent(in), optional :: timeout

    cURL timeout in seconds.
    integer, intent(in), optional :: connect_timeout

    cURL connection timeout in seconds.
    logical, intent(in), optional :: verify_ssl

    Verify SSL cert.

    Return Value integer

public interface dm_mail_out

Generic routine to print mail and server type.

  • private subroutine mail_out_mail(mail, unit)

    Prints mail type to standard output or given file unit.

    Arguments

    Type IntentOptional Attributes Name
    type(mail_type), intent(inout) :: mail

    Mail type.
    integer, intent(in), optional :: unit

    File unit.

  • private subroutine mail_out_server(server, unit)

    Prints mail server type to standard output or given file unit.

    Arguments

    Type IntentOptional Attributes Name
    type(mail_server_type), intent(inout) :: server

    Mail server type.
    integer, intent(in), optional :: unit

    File unit.

Derived Types

type, public ::  mail_server_type

Opaque SMTP server type that stores connection settings.

type, public ::  mail_type

Opaque e-mail type that stores sender, recipients, subject, message, and allocation status.


Functions

public function dm_mail_create_mail(mail, from, to, subject, message, cc, bcc) result(rc)

Creates new mail type and inserts passed values. The function return E_INVALID if given arguments are invalid or incomplete.

Arguments

Type IntentOptional Attributes Name
type(mail_type), intent(out) :: mail

Mail type.
type(person_type), intent(in) :: from

Mail sender.
type(person_type), intent(in) :: to(:)

Mail recipients.
character(len=*), intent(in) :: subject

Mail subject.
character(len=*), intent(in) :: message

Mail message.
type(person_type), intent(in), optional :: cc(:)

Mail CC recipients.
type(person_type), intent(in), optional :: bcc(:)

Mail BCC recipients.

Return Value integer

public function dm_mail_create_server(server, host, username, password, port, tls, timeout, connect_timeout, verify_ssl) result(rc)

Returns SMTP server type. Argument tls may be one of the following:

Read more…

Arguments

Type IntentOptional Attributes Name
type(mail_server_type), intent(out) :: server

Mail server type.
character(len=*), intent(in) :: host

SMTP server host.
character(len=*), intent(in) :: username

SMTP user name.
character(len=*), intent(in) :: password

SMTP password.
integer, intent(in), optional :: port

SMTP server port (or 0).
integer, intent(in), optional :: tls

SMTP transport-layer security.
integer, intent(in), optional :: timeout

cURL timeout in seconds.
integer, intent(in), optional :: connect_timeout

cURL connection timeout in seconds.
logical, intent(in), optional :: verify_ssl

Verify SSL cert.

Return Value integer

public function dm_mail_error(error_curl) result(rc)

Converts cURL easy stack error code to DMPACK error code.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: error_curl

cURL easy error code.

Return Value integer

public function dm_mail_error_message(error_curl) result(message)

Return message associated with given cURL error code as allocatable character string.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: error_curl

cURL error code.

Return Value character(len=:), allocatable

Error message.

public function dm_mail_init() result(rc)

Initialises SMTP backend. The function returns E_MAIL on error.

Arguments

None

Return Value integer

public function dm_mail_send(mail, server, error_message, error_curl, debug) result(rc)

Sends SMTP request by calling libcurl.

Read more…

Arguments

Type IntentOptional Attributes Name
type(mail_type), intent(inout) :: mail

Mail type.
type(mail_server_type), intent(inout) :: server

Mail server type.
character(len=:), intent(out), optional, allocatable :: error_message

Error message.
integer, intent(out), optional :: error_curl

cURL error code.
logical, intent(in), optional :: debug

Output debug messages.

Return Value integer

public function dm_mail_url(host, port, tls) result(url)

Returns allocatable string of SMTP server URL in the form smtp[s]://host[:port]/. Uses the URL API of libcurl to create the URL. By default, Transport Layer Security is disabled.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: host

SMTP server host name.
integer, intent(in), optional :: port

SMTP server port (up to 5 digits).
logical, intent(in), optional :: tls

Transport-layer security.

Return Value character(len=:), allocatable

URL of SMTP server.

public function dm_mail_write(mail) result(payload)

Returns allocatable e-mail string. This function does not verify the allocation state of the given mail type. It has been made public to simplify testing.

Arguments

Type IntentOptional Attributes Name
type(mail_type), intent(inout) :: mail

Mail type.

Return Value character(len=:), allocatable

E-mail data.

public function dm_mail_read_callback(ptr, sz, nmemb, data) result(n) bind(c))

Callback function to upload payload passed via data to the memory chunk in ptr. Do not call this function directly.

Arguments

Type IntentOptional Attributes Name
type(c_ptr), intent(in), value :: ptr

C pointer to a chunk of memory.
integer(kind=c_size_t), intent(in), value :: sz

Always 1.
integer(kind=c_size_t), intent(in), value :: nmemb

Size of the memory chunk.
type(c_ptr), intent(in), value :: data

C pointer to argument passed by caller.

Return Value integer(kind=c_size_t)

Function return value.


Subroutines

public subroutine dm_mail_shutdown()

Cleans up SMTP backend.

Arguments

None