Skip to main content

​
What are tags?

Tags are labels you can attach to emails to organize and categorize them. They help you:
  • Track campaigns: Group emails by marketing campaigns or newsletters
  • Organize by department: Separate transactional emails by department (billing, support, etc.)
  • Filter messages: Quickly find specific types of emails in your dashboard
  • Analyze performance: Compare metrics across different email categories

​
Adding tags to emails

​
Via API

Add a tag field to your API request: 
curl -X POST https://api.lettermint.co/v1/send \
    -H "x-lettermint-token: $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "from": "John Doe <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Welcome to our newsletter",
    "text": "Thank you for subscribing!",
    "tag": "newsletter"
}'

​
Via SMTP

When using SMTP, add the X-LM-Tag header to your email: 
await transporter.sendMail({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Order Confirmation',
    text: 'Your order has been confirmed.',
    headers: {
        'X-LM-Tag': 'order-confirmation'
    }
});

​
Tag format requirements

Tags must follow these rules:
  • Allowed characters: Letters (uppercase and lowercase), numbers, underscores, hyphens, and spaces
  • Pattern: Must match ^[a-zA-Z0-9_-]+(?:\s[a-zA-Z0-9_-]+)*$
  • Maximum length: 255 characters
  • No leading/trailing spaces: Spaces are allowed between words but not at the beginning or end
  • Special characters: Only underscores and hyphens are allowed

​
Valid tag examples

  • ✅ newsletter
  • ✅ Newsletter
  • ✅ order-confirmation
  • ✅ order_confirmation
  • ✅ Order Confirmation
  • ✅ invoice-2024
  • ✅ Invoice_2024
  • ✅ Welcome Email
  • ✅ password-reset
  • ✅ Password_Reset
  • ✅ Order Confirmation 2024

​
Invalid tag examples

  • ❌ Newsletter (starts with space)
  • ❌ Newsletter (ends with space)
  • ❌ invoice@2024 (@ symbol not allowed)
  • ❌ order#123 (# symbol not allowed)
  • ❌ welcome!email (! symbol not allowed)
  • ❌ order.confirmation (. symbol not allowed)

​
Filtering messages

​
Filter by specific tag

Retrieve all messages with a specific tag:
An example of how to filter on tags.

​
Team isolation

Tags are isolated to your team:
  • Each team has its own set of tags
  • Tags with the same name can exist across different teams
  • Switching teams shows only that team’s tags
Tags are created automatically when you first use them. There’s no need to pre-create tags before sending emails.

​
Limitations

  • One tag per message: Each email can have only one tag
  • No tag updates: Once an email is sent, its tag cannot be changed
  • Automatic cleanup: Unused tags (with no associated messages) may be removed during message cleanup

​
Summary

Tags provide a powerful way to organize your email traffic. By following the slug format requirements and using consistent naming conventions, you can effectively categorize, filter, and analyze your email communications. Remember that tags are team-specific and created automatically when first used.