FastAPI Mail

---

1. Basic SMTP Configuration:

from fastapi_mail import FastMail, MessageSchema
from fastapi_mail.smtp import SMTPConfig

config = SMTPConfig(
    host="smtp.gmail.com",
    port=587,
    username="[e-mail]",
    password="your_password",
)

mail = FastMail(config=config)

2. Send a Simple Email:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

3. Send an Email with HTML Template:

template = "<p>Hello, world!</p>"

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    html=template,
)

mail.send_message(message)

4. Send an Email with Attachments:

from path import Path

file_path = Path("path/to/file.txt")

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    attachments=[file_path],
)

mail.send_message(message)

5. Send an Email with Multiple Recipients:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]", "[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

6. Send an Email with BCC Recipients:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    bcc=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

7. Send an Email with Custom Headers:

headers = {"My-Custom-Header": "My Custom Value"}

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    headers=headers,
)

mail.send_message(message)

8. Send an Email with Mailgun Configuration:

from fastapi_mail.mailgun import MailgunConfig

config = MailgunConfig(
    key="YOUR_MAILGUN_API_KEY",
    domain="YOUR_MAILGUN_DOMAIN",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

9. Send an Email with Mandrill Configuration:

from fastapi_mail.mandrill import MandrillConfig

config = MandrillConfig(
    key="YOUR_MANDRILL_API_KEY",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

10. Send an Email with Sendgrid Configuration:

from fastapi_mail.sendgrid import SendgridConfig

config = SendgridConfig(
    key="YOUR_SENDGRID_API_KEY",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

11. Send an Email with Amazon SES Configuration:

from fastapi_mail.ses import AmazonSESConfig

config = AmazonSESConfig(
    key_id="YOUR_ACCESS_KEY_ID",
    secret="YOUR_ACCESS_SECRET",
    region="us-east-1",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

12. Send an Email with GMail OAuth2 Configuration:

from fastapi_mail.gmail import GmailOAuth2TokenConfig

config = GmailOAuth2TokenConfig(
    scopes=["https://mail.googleapis.com/auth/gmail.send"],
    token_path="path/to/token.json",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

13. Send an Email with Custom Sender Address:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    sender="[e-mail]",
)

mail.send_message(message)

14. Send an Email with Reply-To Address:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    reply_to="[e-mail]",
)

mail.send_message(message)

15. Send an Email with Priority:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    priority="high",
)

mail.send_message(message)

16. Send an Email with BCC Recipients:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    bcc=["[e-mail]"],
)

mail.send_message(message)

17. Send an Email with Custom MIME Headers:

headers = {
    "X-Custom-Header-1": "My Custom Value 1",
    "X-Custom-Header-2": "My Custom Value 2",
}

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    mime_headers=headers,
)

mail.send_message(message)

18. Send an Email with HTML Body and Plain Text Body:

html = "<p>Hello, world!</p>"
text = "Hello, world!"

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    html=html,
    text=text,
)

mail.send_message(message)

19. Send an Email with Templates:

from fastapi_mail.helpers import get_message_template

template = get_message_template(
    template_file="path/to/template.html",
    ctx={"name": "John Doe"}
)

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    html=template.html,
    text=template.text,
)

mail.send_message(message)

20. Send an Email with Custom Message ID:

message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    message_id="custom-message-id",
)

mail.send_message(message)

21. Send an Email with Tracking:

from fastapi_mail.fastapi import ConnectionConfig

config = ConnectionConfig(
    enabled_backends=["fastapi_mail.backends.smtp.SmtpBackend"],
    backend_options={"smtp": {"debug": True}}
)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
    track_clicks=True,
    track_opens=True,
)

mail.send_message(message)

22. Send an Email with Rate Limiting:

config = ConnectionConfig(
    enabled_backends=["fastapi_mail.backends.smtp.SmtpBackend"],
    backend_options={"smtp": {"rate_limit": 20, "rate_period": 60}}
)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)

mail.send_message(message)

23. Send an Email with File Embeddings:

from fastapi_mail.message import MessageModel
from fastapi_mail.errors import FastMailException

try:
    file = open("file.txt", "r")
    embed = MessageModel.Attachment(file.read(), "file.txt")
    message = MessageModel(
        subject="Test Email",
        recipients=["[e-mail]"],
        body="Hello, world!",
        attachments=[embed],
    )
    mail.send_message(message)
finally:
    file.close()

24. Send an Email with Inline Embeddings:

from fastapi_mail.message import MessageModel
from fastapi_mail.errors import FastMailException

try:
    file = open("image.png", "rb")
    embed = MessageModel.InlineImage(file.read(), "image.png")
    message = MessageModel(
        subject="Test Email",
        recipients=["[e-mail]"],
        html="<img src='cid:image.png'>",
        inline_attachments=[embed],
    )
    mail.send_message(message)
finally:
    file.close()

25. Send an Email with Multiple Embed Types:

from fastapi_mail.message import MessageModel
from fastapi_mail.errors import FastMailException

try:
    file_doc = open("file.doc", "rb")
    embed_doc = MessageModel.Attachment(file_doc.read(), "file.doc")
    file_png = open("image.png", "rb")
    embed_png = MessageModel.InlineImage(file_png.read(), "image.png")
    message = MessageModel(
        subject="Test Email",
        recipients=["[e-mail]"],
        html="<img src='cid:image.png'>",
        attachments=[embed_doc],
        inline_attachments=[embed_png],
    )
    mail.send_message(message)
finally:
    file_png.close()
    file_doc.close()

26. Send an Email with Custom Configuration:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.smtp import SMTPConfig

custom_config = SMTPConfig(
    host="mail.example.com",
    port=25,
    username="admin",
    password="secret",
)
connection_config = ConnectionConfig(
    SECRET="SECRET_KEY",
    MAIL_USERNAME="admin",
    MAIL_PASSWORD="secret",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
    MAIL_PORT=25,
    MAIL_SERVER="mail.example.com",
    MAIL_TLS=True,
    MAIL_SSL=False,
    USE_CREDENTIALS=True,
    VALIDATE_CERTS=True,
    # Additional configuration options
    _options={
        "disable_authentication": True,
        "timeout": 30,
        "debug": True,
    },
)
mail = FastMail(config=custom_config, connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

27. Send an Email with Custom Template Dir:

from fastapi_mail.helpers import get_message_template
from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.smtp import SMTPConfig

custom_template_dir = "path/to/custom/templates"
custom_config = SMTPConfig(
    host="mail.example.com",
    port=25,
    username="admin",
    password="secret",
)
connection_config = ConnectionConfig(
    SECRET="SECRET_KEY",
    MAIL_USERNAME="admin",
    MAIL_PASSWORD="secret",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
    MAIL_PORT=25,
    MAIL_SERVER="mail.example.com",
    MAIL_TLS=True,
    MAIL_SSL=False,
    USE_CREDENTIALS=True,
    VALIDATE_CERTS=True,
)
mail = FastMail(config=custom_config, connection_config=connection_config, template_directory=custom_template_dir)
template = get_message_template(
    template_file="template.html",
    ctx={"name": "John Doe"}
)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    html=template.html,
    text=template.text,
)
mail.send_message(message)

28. Send an Email with Async Send:

from fastapi_mail.fastapi import ConnectionConfig
from fastapi_mail.smtp import SMTPConfig

async def send_email(message):
    custom_config = SMTPConfig(
        host="mail.example.com",
        port=25,
        username="admin",
        password="secret",
    )
    connection_config = ConnectionConfig(
        SECRET="SECRET_KEY",
        MAIL_USERNAME="admin",
        MAIL_PASSWORD="secret",
        MAIL_FROM="[e-mail]",
        MAIL_FROM_NAME="John Doe",
        MAIL_PORT=25,
        MAIL_SERVER="mail.example.com",
        MAIL_TLS=True,
        MAIL_SSL=False,
        USE_CREDENTIALS=True,
        VALIDATE_CERTS=True,
    )
    mail = FastMail(config=custom_config, connection_config=connection_config)
    await mail.send_message(message)

29. Send an Email with Background Send:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.smtp import SMTPConfig

custom_config = SMTPConfig(
    host="mail.example.com",
    port=25,
    username="admin",
    password="secret",
)
connection_config = ConnectionConfig(
    SECRET="SECRET_KEY",
    MAIL_USERNAME="admin",
    MAIL_PASSWORD="secret",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
    MAIL_PORT=25,
    MAIL_SERVER="mail.example.com",
    MAIL_TLS=True,
    MAIL_SSL=False,
    USE_CREDENTIALS=True,
    VALIDATE_CERTS=True,
    background_tasks=True,
)
mail = FastMail(config=custom_config, connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

30. Send an Email with Celery Background Send:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.smtp import SMTPConfig
from celery.app.task import task

@task
def send_email(message: MessageSchema):
    custom_config = SMTPConfig(
        host="mail.example.com",
        port=25,
        username="admin",
        password="secret",
    )
    connection_config = ConnectionConfig(
        SECRET="SECRET_KEY",
        MAIL_USERNAME="admin",
        MAIL_PASSWORD="secret",
        MAIL_FROM="[e-mail]",
        MAIL_FROM_NAME="John Doe",
        MAIL_PORT=25,
        MAIL_SERVER="mail.example.com",
        MAIL_TLS=True,
        MAIL_SSL=False,
        USE_CREDENTIALS=True,
        VALIDATE_CERTS=True,
        background_tasks=True,
        celery_app=celery_app,
    )
    mail = FastMail(config=custom_config, connection_config=connection_config)
    mail.send_message(message)

31. Send an Email with Sendgrid ConnectionConfig:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.sendgrid import SendgridConfig

connection_config = ConnectionConfig(
    SENDGRID_API_KEY="YOUR_API_KEY",
    SECRET="SECRET_KEY",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

32. Send an Email with Mailgun ConnectionConfig:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.mailgun import MailgunConfig

connection_config = ConnectionConfig(
    MAILGUN_API_KEY="YOUR_API_KEY",
    MAILGUN_DOMAIN="YOUR_DOMAIN",
    SECRET="SECRET_KEY",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

33. Send an Email with Mandrill ConnectionConfig:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.mandrill import MandrillConfig

connection_config = ConnectionConfig(
    MANDRILL_API_KEY="YOUR_API_KEY",
    SECRET="SECRET_KEY",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

34. Send an Email with SES ConnectionConfig:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.ses import AmazonSESConfig

connection_config = ConnectionConfig(
    AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID",
    AWS_SECRET_ACCESS_KEY="YOUR_ACCESS_SECRET_KEY",
    AWS_DEFAULT_REGION="YOUR_DEFAULT_REGION",
    SECRET="SECRET_KEY",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

35. Send an Email with Gmail OAuth2 ConnectionConfig:

from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.gmail import GmailOAuth2TokenConfig

connection_config = ConnectionConfig(
    GMAIL_CLIENT_ID="YOUR_CLIENT_ID",
    GMAIL_CLIENT_SECRET="YOUR_CLIENT_SECRET",
    GMAIL_REFRESH_TOKEN="YOUR_REFRESH_TOKEN",
    SECRET="SECRET_KEY",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    body="Hello, world!",
)
mail.send_message(message)

36. Send an Email with Templates with ConnectionConfig:

from fastapi_mail.helpers import get_message_template
from fastapi_mail.fastapi import FastMail, ConnectionConfig
from fastapi_mail.smtp import SMTPConfig

connection_config = ConnectionConfig(
    SECRET="SECRET_KEY",
    MAIL_USERNAME="admin",
    MAIL_PASSWORD="secret",
    MAIL_FROM="[e-mail]",
    MAIL_FROM_NAME="John Doe",
    MAIL_PORT=25,
    MAIL_SERVER="mail.example.com",
    MAIL_TLS=True,
    MAIL_SSL=False,
    USE_CREDENTIALS=True,
    VALIDATE_CERTS=True,
    template_directory="path/to/templates",
)
template = get_message_template(
    template_file="template.html",
    ctx={"name": "John Doe"}
)
message = MessageSchema(
    subject="Test Email",
    recipients=["[e-mail]"],
    html=template.html,
    text=template.text,
)
mail = FastMail(config=custom_config, connection_config=connection_config)
mail.send_message(message)