Mailgun API

Overview

API Plugin’s Mailgun API provides a simple and reliable way to integrate email functionality into your applications. Use it to send transactional emails, manage mailing lists, and handle subscribers with ease.

Key benefits include:

• Reliable email delivery
• Mailing list management
• HTML and plain text support
• Subscriber management
• Email tracking capabilities
• Multiple recipient options (CC, BCC)
• Custom metadata and tags
• Reply-To functionality
• Easy integration

How to Setup

We assume you have signed up on API Plugin and are logged into the dashboard.

1. Get Mailgun API credentials:

   • Create an account at Mailgun
   • Verify your domain or use Mailgun’s sandbox domain
   • Find your API key in the dashboard
   • Note your Mailgun domain

2. Configure API:

   • Go to API Plugin marketplace
   • Select Mailgun API
   • Input your API key and domain
   • Create API endpoint

Available Endpoints

1. Send Email

POST /v1/{appId}/{token}/send

Parameters (in request body):

• from (required): Sender email address
• to (required): Recipient email address(es)
• subject (required): Email subject
• text: Plain text email content
• html: HTML email content
• cc: CC recipients
• bcc: BCC recipients
• reply_to: Reply-To address(es)
• tags: Tags for the email

Example Request:

{
    "from": "Sender <sender@yourdomain.com>",
    "to": ["recipient@example.com"],
    "subject": "Welcome to Our Service",
    "html": "<h1>Welcome!</h1><p>Thank you for joining our service.</p>",
    "text": "Welcome! Thank you for joining our service.",
    "tags": ["welcome", "onboarding"]
}

2. Get Mailing List Member

GET /v1/{appId}/{token}/member?list_address={list_address}&email={email}

Parameters:

• list_address (required): Mailing list address (e.g., list@yourdomain.com)
• email (required): Email address of the member

3. Update Mailing List Member

PUT /v1/{appId}/{token}/member?list_address={list_address}&email={email}

Parameters:

• list_address (required): Mailing list address
• email (required): Email address of the member
• Request body:

  {
      "name": "Updated Name",
      "vars": {
          "age": 30,
          "interests": ["technology", "marketing"]
      },
      "subscribed": true
  }
  

4. Delete Mailing List Member

DELETE /v1/{appId}/{token}/member?list_address={list_address}&email={email}

Parameters:

• list_address (required): Mailing list address
• email (required): Email address of the member

5. Add Subscriber

POST /v1/{appId}/{token}/subscriber?list_address={list_address}

Parameters:

• list_address (required): Mailing list address
• Request body:

  {
      "email": "new.subscriber@example.com",
      "name": "New Subscriber",
      "vars": {
          "company": "Example Inc.",
          "role": "Developer"
      },
      "subscribed": true
  }
  

Email Best Practices

1. From Address: Use a recognizable domain to improve deliverability. Format as “Name email@domain.com” for better display in email clients.

2. Subject Lines: Keep subject lines clear, relevant, and under 50 characters for optimal open rates.

3. Email Content: Always include both HTML and plain text versions of your email for maximum compatibility.

4. Responsive Design: Ensure HTML emails are responsive for mobile viewing, as over 60% of emails are opened on mobile devices.

5. Tags: Use tags to categorize emails for analytics and tracking purposes.

Example Code

// Send a welcome email
const sendWelcomeEmail = async (user) => {
    try {
        const response = await fetch(`/v1/{appId}/{token}/send`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                from: 'Welcome Team <welcome@yourdomain.com>',
                to: [user.email],
                subject: 'Welcome to Our Platform',
                html: `
          <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
            <h1>Hello ${user.name}!</h1>
            <p>Welcome to our platform. We're excited to have you join us.</p>
            <p>Here are some resources to help you get started:</p>
            <ul>
              <li><a href="https://yourdomain.com/docs">Documentation</a></li>
              <li><a href="https://yourdomain.com/tutorials">Tutorials</a></li>
              <li><a href="https://yourdomain.com/support">Support</a></li>
            </ul>
            <p>If you have any questions, just reply to this email.</p>
          </div>
        `,
                text: `Hello ${user.name}!\n\nWelcome to our platform. We're excited to have you join us.\n\nHere are some resources to help you get started:\n- Documentation: https://yourdomain.com/docs\n- Tutorials: https://yourdomain.com/tutorials\n- Support: https://yourdomain.com/support\n\nIf you have any questions, just reply to this email.`,
                tags: ['welcome', 'onboarding'],
                reply_to: 'support@yourdomain.com',
            }),
        });

        const data = await response.json();
        console.log('Welcome email sent successfully:', data);
        return data;
    } catch (error) {
        console.error('Error sending welcome email:', error);
        throw error;
    }
};

// Add a user to a mailing list
const addToNewsletter = async (user) => {
    try {
        const response = await fetch(`/v1/{appId}/{token}/subscriber?list_address=newsletter@yourdomain.com`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                email: user.email,
                name: user.name,
                vars: {
                    signupDate: new Date().toISOString(),
                    source: user.referral || 'direct',
                },
            }),
        });

        const data = await response.json();
        console.log('User added to newsletter:', data);
        return data;
    } catch (error) {
        console.error('Error adding user to newsletter:', error);
        throw error;
    }
};