# FastAPI Mail

***

**1. Basic SMTP Configuration:**

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

config = SMTPConfig(
    host="smtp.gmail.com",
    port=587,
    username="your_email@gmail.com",
    password="your_password",
)

mail = FastMail(config=config)
```

**2. Send a Simple Email:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**3. Send an Email with HTML Template:**

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

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    html=template,
)

mail.send_message(message)
```

**4. Send an Email with Attachments:**

```python
from path import Path

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

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    attachments=[file_path],
)

mail.send_message(message)
```

**5. Send an Email with Multiple Recipients:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient1@example.com", "recipient2@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**6. Send an Email with BCC Recipients:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    bcc=["bcc_recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**7. Send an Email with Custom Headers:**

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

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    headers=headers,
)

mail.send_message(message)
```

**8. Send an Email with Mailgun Configuration:**

```python
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=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**9. Send an Email with Mandrill Configuration:**

```python
from fastapi_mail.mandrill import MandrillConfig

config = MandrillConfig(
    key="YOUR_MANDRILL_API_KEY",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**10. Send an Email with Sendgrid Configuration:**

```python
from fastapi_mail.sendgrid import SendgridConfig

config = SendgridConfig(
    key="YOUR_SENDGRID_API_KEY",
)

mail = FastMail(config=config)

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**11. Send an Email with Amazon SES Configuration:**

```python
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=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**12. Send an Email with GMail OAuth2 Configuration:**

```python
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=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**13. Send an Email with Custom Sender Address:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    sender="my_custom_sender@example.com",
)

mail.send_message(message)
```

**14. Send an Email with Reply-To Address:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    reply_to="my_reply_to_address@example.com",
)

mail.send_message(message)
```

**15. Send an Email with Priority:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    priority="high",
)

mail.send_message(message)
```

**16. Send an Email with BCC Recipients:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    bcc=["bcc_recipient@example.com"],
)

mail.send_message(message)
```

**17. Send an Email with Custom MIME Headers:**

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

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    mime_headers=headers,
)

mail.send_message(message)
```

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

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

message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    html=html,
    text=text,
)

mail.send_message(message)
```

**19. Send an Email with Templates:**

```python
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=["recipient@example.com"],
    html=template.html,
    text=template.text,
)

mail.send_message(message)
```

**20. Send an Email with Custom Message ID:**

```python
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
    message_id="custom-message-id",
)

mail.send_message(message)
```

**21. Send an Email with Tracking:**

```python
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=["recipient@example.com"],
    body="Hello, world!",
    track_clicks=True,
    track_opens=True,
)

mail.send_message(message)
```

**22. Send an Email with Rate Limiting:**

```python
config = ConnectionConfig(
    enabled_backends=["fastapi_mail.backends.smtp.SmtpBackend"],
    backend_options={"smtp": {"rate_limit": 20, "rate_period": 60}}
)
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)

mail.send_message(message)
```

**23. Send an Email with File Embeddings:**

```python
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=["recipient@example.com"],
        body="Hello, world!",
        attachments=[embed],
    )
    mail.send_message(message)
finally:
    file.close()
```

**24. Send an Email with Inline Embeddings:**

```python
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=["recipient@example.com"],
        html="<img src='cid:image.png'>",
        inline_attachments=[embed],
    )
    mail.send_message(message)
finally:
    file.close()
```

**25. Send an Email with Multiple Embed Types:**

```python
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=["recipient@example.com"],
        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:**

```python
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="admin@example.com",
    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=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**27. Send an Email with Custom Template Dir:**

```python
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="admin@example.com",
    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=["recipient@example.com"],
    html=template.html,
    text=template.text,
)
mail.send_message(message)
```

**28. Send an Email with Async Send:**

```python
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="admin@example.com",
        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:**

```python
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="admin@example.com",
    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=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**30. Send an Email with Celery Background Send:**

```python
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="admin@example.com",
        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:**

```python
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="admin@example.com",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**32. Send an Email with Mailgun ConnectionConfig:**

```python
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="admin@example.com",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**33. Send an Email with Mandrill ConnectionConfig:**

```python
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="admin@example.com",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**34. Send an Email with SES ConnectionConfig:**

```python
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="admin@example.com",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**35. Send an Email with Gmail OAuth2 ConnectionConfig:**

```python
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="admin@example.com",
    MAIL_FROM_NAME="John Doe",
)
mail = FastMail(connection_config=connection_config)
message = MessageSchema(
    subject="Test Email",
    recipients=["recipient@example.com"],
    body="Hello, world!",
)
mail.send_message(message)
```

**36. Send an Email with Templates with ConnectionConfig:**

```python
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="admin@example.com",
    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=["recipient@example.com"],
    html=template.html,
    text=template.text,
)
mail = FastMail(config=custom_config, connection_config=connection_config)
mail.send_message(message)
```