Transactional E-Mail Service: SMTP Relay & E-Mail API

SMTP

You can find detailed documentation on the SMTP API under the following link:

SMTP-API Documentation

---

1. What is the difference between the REST API and SMTP Relay?

Both the REST API and SMTP Relay enable email submission, but they serve different use cases:

• API: Offers advanced control, allowing programmatic management of emails with features like detailed tracking, metadata, and status retrieval.
• SMTP Relay: A simpler method for email submission that uses standard headers for personalization and tracking.

 

2. Why should I use Maileon instead of building my own email system?

Maileon streamlines email delivery by handling deliverability, IP reputation, and scaling, ensuring reliable delivery of transactional messages. It also provides compliance tools, actionable insights, and reduces the operational complexity of maintaining a proprietary system.

3. Can I use the Maileon Transactional Emails Service to send bulk marketing emails?

No, the Maileon Transactional Emails Service is designed for transactional emails only. For marketing campaigns, consider using Maileon’s dedicated email marketing platform.

4. What are transactional emails, and why are they important?

Transactional emails are automated messages triggered by user actions, such as registration or purchase confirmation. They enhance customer experience, build trust, and deliver critical information promptly.

5. What is the difference between transactional and promotional emails?

• Transactional Emails: Triggered by user actions, such as order confirmations or password resets.
• Promotional Emails: Designed for marketing purposes, such as newsletters or sales announcements.

 

6. How can I track emails submitted with the SMTP Relay?

Use the X-Custom-Id header to assign a unique identifier to each email. This custom ID enables tracking of the email’s lifecycle via Maileon’s API endpoints, such as /messages or /ingestions. This process allows you to monitor delivery, opens, clicks or rejections.

7. How does Maileon handle duplicate message submissions?

If the same custom_id is reused in subsequent submissions, Maileon treats them as separate messages. Ensure custom_id values are unique for better tracking.

8. How can I include additional information in emails sent through SMTP Relay?

Use the X-Metadata header to include custom data in JSON format, such as {“user_id”: “12345”, “campaign”: “promo”}. This metadata is logged with email events and can be retrieved via the API for analysis or debugging.

9. How can I track if recipients open or click links in my emails?

Include the following headers in your email submission:

• X-Track-Opens: yes to enable open tracking.
• X-Track-Clicks: html_and_text to enable click tracking.

Tracking information is logged in the /opens and /clicks API endpoints, allowing you to monitor recipient interactions.

10. How do I automatically append parameters to URLs?

To add custom parameters to tracked URLs, use:

• API: The url_tags attribute.
• SMTP Relay: the X-Url-Tags header.

For instance, setting utm_source=email&utm_medium=email_marketing will append this query string to all tracked links, aiding in campaign attribution.

11. Can I customize the tracking links in my emails?

Yes, use the X-Url-Tags header (SMTP Relay) or url_tags attribute (API) to append custom parameters to tracking links for campaign attribution.

12. Why aren’t my opens being tracked despite correct settings?

Open tracking issues may arise due to:

• Lack of HTML content (tracking requires a pixel in the HTML).
• Recipients disabling image loading in their email client.
• Filtering of bot or automated opens by Maileon.

Solution: Ensure your email contains HTML, inform recipients about enabling images, and complement open tracking with click tracking for better engagement measurement.

13. Does Maileon recognize iOS 15 Mail Privacy Protection opens?

Maileon employs techniques to filter out artificial opens caused by iOS 15 Mail Privacy Protection and similar bots. While Maileon continuously enhances its detection methods, no system guarantees 100& accuracy in filtering automated opens.

14. Why aren’t my clicks being tracking despite correct settings?

Click tracking may fail due to:

• Malformed or non-HTTP/HTTPS URLs.
• Tracking not enabled (track_clicks in API or X-Track-Clicks in SMTP Relay).
• Recipient email client blocking tracking links.

Solution: Verify all links in the email, enable click tracking, and ensure the recipient’s email client supports tracking.

15. What details does Maileon provide for opens and clicks?

For each open or click event, Maileon records:

• User Agent (browser/application).
• Device Type (e.g., phone, tablet, desktop). Operating System and Version.

This information is accessible via the /opens and /clicks API endpoints, providing detailed insights into recipient behavior and device usage.

16. Can I send emails with different content types (e.g., HTML and text)?

Yes, you can include both HTML and plain-text versions of your email in the same submission.

17. What email formats does Maileon support?

Maileon supports HTML and plain-text formats. You can include both in the same email to ensure compatibility with all email clients.

18. How do I personalize emails sent through SMTP Relay?

To personalize emails:

• Use the X-Substitution-Data header to include JSON-formatted data,
  e.g., { “name”: “Alice” } . Combine this with placeholders in your email content, such as {{name}} (example in liquid syntax), to dynamically replace text for each recipient.
• Specify the templating language using the X-Templating-Language header. Supported languages include liquid, mustache and handlebars

 

19. What are the benefits of using substitution data for personalization?

Substitution data allows you to dynamically customize email content, making emails more relevant and increasing engagement rates.

20. How can I test my SMTP Relay configuration before sending live emails?

Use the X-Sandbox: true header to simulate email submission without actual delivery. This enables you to verify email ingestion, header
correctness, and overall configuration while preventing emails from being sent to recipients.

21. How can I send an email using the API?

Use the /message-transmissions endpoint to submit a request. Include the following fields in your payload:

• Recipient Details: List of email addresses in the to, cc, or bcc fields.
• Email Content: subject, html or text, and optional substitution_data.
• Tracking Options: Attributes like track_opens or track_clicks.

 

22. What should I do if my email is rejected?

Emails may be rejected for the following reasons:

• Invalid Sender Address: Ensure the sender domain matches your Maileon account’s verified domain.
• Recipient Suppression: The recipient email in on a suppression list due to previous bounces or complaints.
• Invalid Email Content or Settings: Missing mandatory fields, malformed JSON, invalid headers etc.

Solution: Review the rejection details using the /rejections endpoint. Correct the identified issues and resubmit the email.

23. Can I resend a failed email?

Yes, but resending must be done manually. Use the /rejections endpoints to identify the failed email and submit it again with corrections.

24. Why are my emails being rejected due to policy violations?

Rejections for policy violations may occur if:

• Your email content violates Maileon’s Acceptable Use Policy.
• The recipient’s address is on a suppression list.

Review the rejection details using the /rejections endpoint and adjust your email accordingly.

25. How can I track the status of submitted emails?

Track emails by querying these endpoints:

• /messages: Details of the email.
• /ingestions: To check if the email was successfully ingested.
• /queued: To see if the email is queued for delivery.
• /rejections: For rejected emails.
• /opens and /clicks: For engagement events.
• /bounces and /complaints: For failed or reported emails.

Use filters like msg_id, custom_id, or recipient_email to narrow your search.

26. Can I cancel or delete emails that are queued for delivery?

No, Maileon does not allow deletion of queued emails to ensure consistent processing and tracking. Once queued, emails proceed through delivery attempts or are marked as failed if undeliverable.

27. How can I get an overview of my email performance?

Use the /metrics-data-points endpoint to retrieve aggregated metrics like opens, clicks, and bounces. This provides an overview of email performance over a specified interval. Example Request: GET /metrics-datapoints?interval=day

28. How can I filter metrics by campaign or tag?

Add the tag parameter to your /metrics-data-points request to filter metrics by campaign or category. Example: To get daily metrics for a “welcome” campaign: GET /metrics-data-points?interval=day&tag=welcome_email

29. What time intervals can I use for metrics?

The /metrics-data-points endpoint supports the following intervals:

• hour: Provides detailed metrics at an hourly granularity.
• day: Summarizes metrics by day, aligned with Berlin’s time zone.
• month: Aggregates metrics for the entire month, also aligned with Berlin’s time zone.

 

30. Can I filter metrics by tags or time range?

Yes. Use these parameters in your request:

• tag: Filter metrics by campaign, email category, or specific tags assigned during email submission.
• filter: Specify a time range using conditions such as greater-or-equal or less-or-equal.

Example request: GET /metrics-datapoints?interval=day&tag=promo&filter=greater-or-equal(data_point,2023-1201T00:00:00Z)

31. What types of metrics are available?

The following metrics are available through the /metrics-data-points endpoint:

• ingestions: Total emails submitted to Maileon.
• queued: Emails successfully queued for delivery.
• rejections: Emails rejected during validation.
• bounces: Emails that failed to deliver.
• opens: Total number of email opens.
• clicks: Total number of link clicks.
• complaints: Reports of spam or abuse.

 

32. Why don’t I see metrics for my emails?

Metrics may be missing for the following reasons:

• Emails were not sent during the specified time range. Ensure the date range in your request matches the email sending period.
• Tags or filters used in the request don’t match the actual tags assigned to your emails.
• Tracking was disabled. Ensure track_opens and track_clicks were enabled during email submission.

Solution: Verify your query parameters and confirm tracking was enabled. Additionally, check the /ingestions endpoint to ensure emails were successfully submitted.

33. How can I send emails to multiple recipients using To, Cc, and Bcc fields?

Maileon supports the use of To, Cc, and Bcc fields for sending emails to multiple recipients:

• To: Used for primary recipients of the email.
• Cc: Used for additional recipients.
• Bcc: Used for blind carbon copy recipients.

Each recipient in any of these fields is treated as unique recipient for tracking and analytics purposes.

34. Are the events (opens, clicks, etc.) of Cc and Bcc recipients attributed to the To recipient?

No, events are attributed to the specific recipient, regardless of whether they were listed in the To, Cc, or Bcc fields. This ensures accurate tracking and attribution of engagement metrics for each individual recipient.

35. How does Maileon handle email duplication across recipients?

Maileon processes each recipient independently. If the same content is sent to multiple recipients, tracking and analytics are recorded per recipient.

36. How does the maximum recipient limit work for SMTP Relay and API?

The SMTP Relay and API both support a maximum of 20 recipients per email address the To, Cc, and Bcc fields.

• Each recipient generates an individual email, meaning an email sent to 20 recipients results in 20 emails being processed.
• Tracking and analytics are performed independently for each recipient.

 

37. Is there a limit to the number of recipients I can include in one email?

Yes, the maximum is 20 recipients per email across all fields (To, Cc, and Bcc). For larger recipient lists, submit multiple API requests or emails via the SMTP Relay to comply with this limit.

38. Can I resend an email to the same recipient?

Yes, you can resend emails, but ensure you’re not violating anti-spam policies.

39. Can I resend a soft-bounced email?

Yes, but Maileon does not retry soft-bounced emails automatically. You can resend manually after addressing the issue.

40. How do I personalize emails sent through the API?

Personalize emails by using substitution data and templates. You can choose one of the following approaches:

1. Direct Content:
   • Provide HTML and/or text content directly in your API request.
   • Use a supported templating language (e.g., Liquid) to define dynamic content within the HTML or text. Specify the templating language in your request.
   • Add substitution data to personalize the content dynamically.
2. Predefined Templates:
   • Reference a pre-saved template by including its template ID in your request.
   • Use substitution data to personalize the template’s content for each recipient.

 

41. Which parts of the email can be personalized?

You can personalize the following parts of your email using substitution data:

• HTML content.
• Text content.
• Subject line.
• Sender name.
• Recipient names (To, Cc, Bcc). Be careful to specify distinct substitution data for each recipient to prevent incorrect personalization, especially when using Cc and Bcc.
• Reply-To name.
• Email header names.

 

42. How can I personalize emails for multiple recipients?

Use the substitution_data field in the recipient’s object to include personalized values for each recipient.

43. Which templating languages are supported?

Maileon supports the following templating languages:

• Liquid
• Mustache
• Handlebars
• Jinja

 

44. Which templating language better suits my needs?

While all supported languages offer powerful features for email templating, Liquid is generally the more versatile and flexible option for most use cases.
Liquid:

• Simplicity: Easy to learn and use, making it ideal for beginners.
• Robustness: Offers a wide range of built-in filters and tags for complex logic and data manipulation.
• Versatility: Suitable for a wide range of use cases, from simple textbased emails to complex HTML templates.

Handlebars/Mustache:

• Clean Syntax: Provides a clean and concise syntax for creating readable templates.
• Basic Templating: Well-suited for basic templating tasks, such as inserting dynamic content into a static template.

Criteria to Consider:

• Complexity of Templates: If you need to create simple templates with basic personalization, Liquid is a good starting point. For more complex templates with advanced logic and dynamic content, Handlebars might be a better fit.
• Team Expertise: If your team is already familiar with a particular language, it might be easier to stick with that choice.
• Long-Term Maintainability: Consider the long-term maintainability of your templates. A clean and well-structured template, regardless of the language, will be easier to update and manage.

Ultimately, the best way to choose the right templating language is to experiment with both and see which one suits your workflow and preferences.

45. Are there any restrictions to the templating languages?

Yes, the following restrictions apply:

• Endless loops in templates are prohibited.
• Template processing for a recipient must complete within a specified timeout; otherwise, the email generation is considered failed, and the email is rejected.
• Loading external resources (e.g., macros, remote files) is forbidden during template processing.

 

46. What happens if substitution data is missing?

If a placeholder in your template lacks corresponding substitution data, its behavior depends on the templating language:

• Liquid: Displays the placeholder as-is (e.g., {{name}}) unless a default value is specified using {{name | default: “Customer”}}.
• Mustache: Removes the placeholder from the output entirely.
• Handlebars: Displays the placeholder as-is unless a fallback value is explicitly defined.

Solution: Always provide default values or validate substitution data before submission.

47. Can I send different templates to different recipients in one request?

No, all recipients in a single API request must use the same template or content. To use different templates, submit separate requests for each group of recipients.

48. Can I save templates in my account?

Yes, you can save up to 100 templates in your Maileon account. These templates can be referenced using a template ID in an API request for message submission, allowing you to reuse content without including it directly in the payload.

Note: Templates cannot be used with SMTP Relay submissions.

49. What happens if I reach my account’s template limit?

You cannot save additional templates until you delete unused ones. Review your templates periodically to manage space effectively.

50. How can I delete a template from my account?

Use the /templates/{template_id} endpoint with the DELETE method to remove a saved template. Note that this action is permanent.

51. Can Maileon automatically generate text content from the provided HTML content?

Yes, Maileon can automatically generate text content from the provided HTML content:

• SMTP Relay: Use the X-Auto-Text header to enable this feature.
• API: Use the auto_text attribute.

Auto-text generation occurs after personalization, meaning the generated plain-text version is based on the personalized HTML content.

52. Can I add custom headers to my email?

Yes, you can include up to 10 custom headers in each email. These headers can be used to provide additional metadata or configurations for specific use cases.

53. Can I specify a Reply-To address for my emails?

Yes, you can specify a custom Reply-To address. This allows recipients to reply to a designated address instead of the sender address.

54. Can I add attachments to my emails?

Yes, you can include up to 10 attachments in each email. Attachments allow you to provide additional content, such as invoices or documents.

55. What is the maximum size of email attachments?

Each attachment can be up to 5 MB in size. Ensure attachments are optimized to meet this limit.

56. What happens if an invalid attachment is included in an email?

If an attachment exceeds the size limit (5 MB) or has supported file types, the email will be rejected during ingestion. Review the rejection details via the /rejections endpoint.

57. Can I add inline images to my emails?

Yes, you can include up to 10 inline images in your emails. Inline images enhance email design by embedding visuals directly into the content.

58. What is the maximum size of in inline images?

Each inline image can be up to 5 MB in size. Ensure images are properly compressed to reduce size without compromising quality.

59. Is there a limit to the message size?

Yes, the overall size limit for an email, including attachments and inline images, is 10 MB. Ensure the total size of all components meets this restriction.

60. What is the difference between soft and hard bounces?

• Soft Bounce: A temporary issue preventing email delivery (e.g., full inbox, server downtime).
• Hard Bounce: A permanent failure (e.g., invalid or non-existent email address). Hard-bounced addresses are added to the bounce suppression list.

 

61. How does Maileon handle hard bounces?

Maileon automatically adds hard-bounced email addresses to the suppression list. This prevents future delivery attempts to these invalid addresses, ensuring better deliverability and reputation management.

62. Where can I find details about bounced emails?

Use the /bounces endpoint to retrieve information about failed deliveries. You can filter the results by:

• Recipient email.
• msg_id.
• custom_id

 

63. Does Maileon resend soft-bounced emails?

No, Maileon does not automatically resend emails that encounter a soft bounce. This allows you to decide whether to resend based on the urgency of the message or to use alternative communication channels to reach the recipient.

64. Does Maileon automatically handle email retries for delivery errors?

No, Maileon does not automatically retry emails for soft bounces or temporary errors. You must decide whether to retry based on the specific error details.

65. What is a complaint?

A complaint occurs when a recipient marks an email as spam or junk.
Complaints are handled as follows:

• The address is automatically added to the complaint suppression list, preventing future emails from being sent to that recipient.
• Complaints may not always be linked to a specific message, depending on how they are reported to Maileon.
• Note that not all email service providers report complaints to Maileon.

 

66. How does Maileon handle complaints reported by ISPs?

When an ISP reports a complaint, the recipient’s email address is automatically added to the complaint suppression list. Complaints may not always be traceable to a specific email due to ISP policies.

67. What happens if a recipient marks my email as spam?

The recipient’s email address is added to the complaint suppression list. This prevents future emails from being sent to the recipient to protect your sender reputation.

68. Can I remove an email address from the complaint suppression list?

No, email addresses on the complaint suppression list cannot be removed. This policy protects your sender reputation and ensures compliance with antispam regulations.

69. How do I handle recipient complaints?

Complaints are automatically added to the suppression list. Regularly monitor your /complaints endpoint and adjust your email practices to reduce complaint rates. Do not attempt to send additional emails to recipients, who complained.

70. How can I track performance of a specific campaign?

Assign tags to your emails (e.g., “welcome_emails”) during submission. Then, use the /metrics-data-points endpoint to retrieve performance metrics for the assigned tag.
Example request: GET /metrics-datapoints?interval=day&tag=welcome_emails

71. How can I assign tags to my emails?

Tags can be assigned during email submission to categorize and track performance:

• SMTP Relay: Use the X-Tags header and include a JSON array of tags.
  Example: X-Tags: [“promo”, “spring”]
• API: Include the tags fields in the email payload.

 

72. Is there a limit to the number of tags I can use?

Each email can have a maximum of 10 tags.
There is an account-wide limit of 100 unique tags. Ensure tags are meaningful and reused where applicable to stay within these limits.

73. What is the retention period for messages and statistics?

Retention periods vary based on the type of data:

• Messages (/messages endpoint): Retained for 20 days.
• Events (e.g., ingestions, queued, rejections, opens, clicks, bounces, complaints): Retained for 10 days.
• Hourly Stats: Retained for 30 days.
• Daily Stats: Retained for 365 days.
• Monthly Stats: No deletion; retained indefinitely.

 

74. What happens if my API key is compromised?

If your API key is compromised:

• Revoke the key immediately via your Maileon account dashboard.
• Generate a new API key and update your integration.
• Monitor your account for unusual activity.

 

75. What happens if I exceed the API rate limit?

If the rate limit is exceeded, Maileon responds with a 429 Too Many Requests error. Check the X-Rate-Limit-Retry-After-Seconds header to determine when you can retry.

76. Can I schedule emails for future delivery?

Maileon does not natively support scheduling emails for future delivery. You can implement scheduling within your application by submitting emails to Maileon at the desired time.

77. Can I send emails to recipients in different time zones?

Maileon does not natively support time-zone-based scheduling. Implement scheduling in your application to send emails at the right time for each recipient.

78. Does Maileon support webhooks for real-time updates?

No, webhooks are not currently supported. Use the polling endpoints (e.g., /opens, /clicks, /bounces) to retrieve updates.

79. How do I mange unsubscribe links in emails?

Maileon does not support unsubscribe link generation for transactional emails yet. Include custom unsubscribe links manually if needed.

80. How can I search for a specific email?

Use the /messages or /ingestions endpoints with filters like msg_id, custom_id, or recipient_email to search for a specific email.

81. What tools can I use to validate email rendering?

Use email testing tools like Litmus or Email on Acid to preview your emails in various clients and ensure proper rendering.

82. How can I ensure my email content complies with accessibility standards?

Ensure your emails follow accessibility guidelines, such as:

• Adding meaningful alt text for images.
• Using semantic HTML for proper structure.
• Including sufficient contract between text and background colors.

 

83. Does Maileon support international characters in emails?

Yes, Maileon fully supports UTF-8 encoding, allowing the use of international characters in email content, and subject lines.

84. Does Maileon support IPv6 for email delivery?

Yes, Maileon supports both IPv4 and IPv6 for email delivery, ensuring compatibility with modern mail servers.

85. How can I test email delivery to specific providers?

Create test email accounts with major providers (e.g., Gmail, Yahoo, Outlook) and send test emails to monitor deliverability and rendering.

86. Does Maileon support A/B testing for transactional emails?

No, Maileon does not natively support A/B testing. You can implement A/B testing in your application by splitting your audience and analyzing metrics via Maileon’s endpoints.

87. What is the difference between the msg_id and custom_id?

• msg_id: A unique identifier assigned by Maileon to each email.
• custom_id: A user-defined identifier, allowing custom tracking and mapping to external systems.

 

88. Can I track email forwards?

No, Maileon does not track forwarded emails as these are handled by the recipient’s email client and are not part of the original email’s tracking.

89. What happens if my email template contains invalid syntax?

Emails with invalid template syntax are rejected during processing. Review the rejection message for specific errors and fix the template.

90. How do I manage sender aliases for multiple brands?

Use different sender names (aliases) and local parts while ensuring the domain matches your verified domains in Maileon.

91. Does Maileon support preheader text?

Yes, include a preheader in your email content. This is often the first line of the plain-text version and is displayed as a preview in email clients.

92. What happens if an email address is misspelled?

Misspelled addresses are rejected during validation if the domain is invalid.