Mailgun API Essential Guide

What type of API does Mailgun provide?

Mailgun uses a RESTful API. Here are the key points about Mailgun's API:

API Type

Mailgun has a RESTful API.

Key Characteristics

The Mailgun API has the following characteristics:

• Uses predictable, resource-oriented URLs
• Uses built-in HTTP capabilities for passing parameters and authentication
• Responds with standard HTTP response codes to indicate errors
• Returns JSON

Authentication

Authentication is done using HTTP Basic Auth with API keys. Mailgun provides two types of API keys:

1. Primary account API key - allows full access to all API endpoints
2. Domain Sending Keys - only allow sending messages for a specific domain

Base URLs

Mailgun provides separate base URLs for US and EU regions:

• US: https://api.mailgun.net/
• EU: https://api.eu.mailgun.net/

Does the Mailgun API have webhooks?

Yes, the official Mailgun API does support webhooks. Here are the key points about Mailgun's webhook functionality:

Webhook Support

Mailgun provides webhooks that allow you to receive real-time notifications about various email events.

Event Types

You can subscribe to the following types of events via Mailgun webhooks:

• Opened - when a recipient opens an email
• Clicked - when a recipient clicks a link in an email
• Unsubscribed - when a recipient unsubscribes
• Complained - when a recipient reports an email as spam
• Delivered - when an email is successfully delivered
• Permanent Fail - when an email permanently fails to deliver (e.g. hard bounce)
• Temporary Fail - when an email temporarily fails to deliver (e.g. soft bounce)

Webhook Data

The webhook payload includes details about the event, such as:

• Event type
• Recipient email address
• Message ID
• Timestamp
• Domain
• Message headers

However, it does not include the full email subject or body by default.

Setting Up Webhooks

You can configure webhooks through the Mailgun dashboard or API. You can set up to 3 webhook URLs per event type.

Security

Mailgun signs each webhook request with a timestamp, token and signature that you can verify for security.

Best Practices

• Handle webhooks asynchronously to manage event spikes
• Use the unique message ID to correlate events with your sent messages
• Consider storing additional email metadata in your own database if you need details not provided in the webhook payload

In summary, while Mailgun webhooks provide robust event tracking, you may need to implement some additional logic to associate events with full message details if required for your use case. The webhooks provide a real-time push mechanism for email event data that can be very useful for tracking engagement and deliverability.

Rate Limits and other limitations

Based on the search results provided, I don't have specific information about the exact API rate limits for Mailgun. However, I can provide some general information about rate limiting in email APIs and Mailgun's approach:

Rate Limiting in Email APIs

Rate limiting is a common technique used by email service providers to restrict traffic and ensure fair use of their APIs. For email APIs, rate limiting typically refers to:

1. Limiting the number of API calls an organization can make during a set period
2. Impacting the number of emails that can be sent during that time frame

Key Points about Rate Limiting

• It helps protect infrastructure from potential abuse or overuse
• It's a way to secure websites from cyber attacks
• It helps manage overall network traffic

Mailgun's Approach to Rate Limiting

While the search results don't provide specific numbers for Mailgun's rate limits, we can infer a few things:

1. Mailgun likely implements some form of rate limiting on their API
2. The limits may vary depending on the type of account or plan you have
3. There are indications that Mailgun has hourly sending limitations for some accounts

Best Practices

When working with Mailgun's API, consider the following:

1. Check Mailgun's official documentation for the most up-to-date information on rate limits
2. Monitor your API usage to ensure you're not exceeding any limits
3. If you need to send a large volume of emails, consider spreading them out over time or upgrading your plan if necessary
4. Use Mailgun's libraries or a reliable HTTP/REST library when making API calls

Additional Information

• Mailgun offers both US and EU regions for sending and receiving emails. Be sure to use the appropriate base URL for your region
• Authentication for the Mailgun API is done using HTTP Basic Auth with an API key
• Mailgun provides two types of API keys: a primary account API key and domain-specific sending keys

If you need specific information about your account's rate limits or if you're experiencing issues related to rate limiting, it's best to contact Mailgun's support directly for the most accurate and up-to-date information.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Mailgun API:

Current API Version

The most recent version of the Mailgun API is v3. This can be seen in the base URL format provided:

https://api.mailgun.net/v3/

Key Points

1. Mailgun uses URI versioning for their API endpoints, with v3 being the current version.

2. Some endpoints may have different versions, so it's important to reference the version stated in the URL for each specific endpoint.

3. The default API version was changed to v3 in July 2019, as announced in a product update.

4. Mailgun's API is RESTful and uses HTTP, with JSON responses.

5. The API supports both US and EU regions, with different base URLs for each:

   • US: https://api.mailgun.net/
   • EU: https://api.eu.mailgun.net/

6. Authentication is done using HTTP Basic Auth with API keys.

Best Practices

1. Always use the appropriate base URL based on your domain's region (US or EU).

2. Keep your API keys secure and use domain-specific sending keys when possible for enhanced security.

3. Refer to the official Mailgun documentation for the most up-to-date information on API endpoints and features.

4. Utilize Mailgun's provided libraries or your preferred HTTP/REST library when making API calls.

In summary, the most recent version of the Mailgun API is v3, but it's crucial to check the specific endpoint documentation as some endpoints may have different versions. Always use the appropriate regional base URL and follow Mailgun's authentication and security best practices when integrating with their API.

How to get a Mailgun developer account and API Keys?

Here are the key steps to get a developer account for Mailgun and create an API integration:

1. Sign up for a Mailgun account:

• Go to the Mailgun website and click "Sign Up".
• Fill out the registration form with your details to create an account.

2. Verify your domain:

• Add and verify a domain you own in the Mailgun dashboard.
• If you don't have a domain, you can use the provided sandbox domain for testing initially.

3. Get your API credentials:

• Once logged in, go to the API Keys section in your Mailgun dashboard.
• You'll see your primary account API key here. This allows full access to all API endpoints.
• For better security, you can create domain-specific sending API keys with limited permissions.

4. Choose how to integrate:

• Mailgun offers both SMTP and API integration options.
• The API is generally recommended for better performance and flexibility.

5. Select a programming language:

• Mailgun provides official SDKs and code examples for popular languages like Python, PHP, Ruby, etc.
• Choose the language you want to use for your integration.

6. Start integrating:

• Use the API key and domain information to configure the Mailgun SDK or make API calls directly.
• Refer to Mailgun's API documentation for details on available endpoints and parameters.

What can you do with the Mailgun API?

Here's the markdown text with the trailing list of URLs and citation references removed, and any URLs inside the content formatted correctly for the markdown file format:

Here's a list of data models you can interact with using the Mailgun API, along with what is possible for each:

Messages

• Send transactional and bulk emails programmatically
• Support for plain text and HTML email formats
• Personalization and dynamic content capabilities
• Attach data to messages for later retrieval
• Use templates for consistent email designs
• Batch sending to multiple recipients in a single API call

Email Tracking

• Monitor delivery status of sent emails
• Track email opens and clicks
• Track email bounces
• Retrieve detailed event data for email analytics

Mailing Lists

• Create and manage mailing lists
• Add and remove subscribers
• Segment subscribers based on various criteria
• Send emails to entire mailing lists

Domains

• Add and verify sending domains
• Manage domain settings and configurations

Templates

• Create and store email templates
• Manage multiple versions of templates
• Use templates in email sending operations

Suppressions

• Manage bounces, complaints, and unsubscribes
• Add or remove email addresses from suppression lists

Webhooks

• Set up and manage webhooks for real-time event notifications
• Receive notifications for various email events (e.g., deliveries, opens, clicks)

Inbound Routing

• Set up rules for handling incoming emails
• Process and route incoming emails to specific endpoints or applications

API Keys

• Create and manage API keys for authentication
• Control access to different API functionalities

Stats

• Retrieve aggregated statistics on email performance
• Access detailed analytics on email campaigns

Validations

• Validate email addresses to improve deliverability
• Check the syntax and domain of email addresses

IP Pools

• Manage dedicated IP addresses
• Create and configure IP pools for sending emails

This list covers the main data models and functionalities provided by the Mailgun API. Each of these models allows for various operations such as creating, reading, updating, and deleting (CRUD) where applicable, as well as specific actions related to email sending and management.