Email Sending

Email Sending

mailiam provides a powerful API for sending transactional and marketing emails. Built on AWS SES with global infrastructure, it delivers emails quickly and reliably to any destination.

Quick Start

1. Get API Access

Create an API key:

curl -X POST https://api.mailiam.dev/auth/keys \
  -H "Authorization: Bearer your-token" \
  -d '{
    "name": "Production App",
    "permissions": ["email.send"]
  }'

2. Send Your First Email

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Welcome to our service!",
    "text": "Thanks for signing up!",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up!</p>"
  }'

Response:

{
  "success": true,
  "messageId": "msg_abc123",
  "status": "queued"
}

That’s it! Your email is now being delivered.

Sending Methods

Simple Email

Send a basic text/HTML email:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Account Update",
    "text": "Your account has been updated successfully.",
    "html": "<p>Your account has been <strong>updated</strong> successfully.</p>",
    "from": "noreply@yourdomain.com"
  }'

Multiple Recipients

Send to multiple recipients:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user1@example.com", "user2@example.com"],
    "cc": ["manager@company.com"],
    "bcc": ["archive@company.com"],
    "subject": "Team Update",
    "html": "<p>Here is the weekly team update...</p>"
  }'

Email with Attachments

Send emails with file attachments:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -F "to=customer@example.com" \
  -F "subject=Your Invoice" \
  -F "html=<p>Please find your invoice attached.</p>" \
  -F "attachments=@/path/to/invoice.pdf" \
  -F "attachments=@/path/to/receipt.png"

Templated Emails

Use email templates with variables:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "template": "welcome-email",
    "variables": {
      "firstName": "John",
      "companyName": "Acme Corp",
      "activationLink": "https://app.com/activate?token=abc123"
    }
  }'

Advanced Features

Custom Headers

Add custom email headers:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Order Confirmation",
    "html": "<p>Your order has been confirmed.</p>",
    "headers": {
      "X-Order-ID": "12345",
      "X-Customer-Type": "premium",
      "Reply-To": "support@company.com"
    }
  }'

Scheduled Sending

Schedule emails for future delivery:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Reminder: Meeting Tomorrow",
    "html": "<p>Don`t forget about our meeting tomorrow at 2 PM.</p>",
    "scheduleFor": "2024-01-15T14:00:00Z"
  }'

Priority Sending

Set email priority for urgent messages:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "admin@company.com",
    "subject": "URGENT: Server Alert",
    "text": "Server is experiencing high CPU usage",
    "priority": "high"
  }'

Tracking Options

Enable email tracking:

curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Product Newsletter",
    "html": "<p>Check out our latest products...</p>",
    "tracking": {
      "opens": true,
      "clicks": true,
      "unsubscribe": true
    }
  }'

Email Templates

Creating Templates

Create reusable email templates:

curl -X POST https://api.mailiam.dev/email/templates \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome-email",
    "subject": "Welcome to {{companyName}}!",
    "html": "<h1>Welcome {{firstName}}!</h1><p>Thanks for joining {{companyName}}.</p><a href=\"{{activationLink}}\">Activate your account</a>",
    "text": "Welcome {{firstName}}! Thanks for joining {{companyName}}. Activate your account: {{activationLink}}"
  }'

Template Variables

Supported variable types:

• Text: {{firstName}}, {{companyName}}
• URLs: {{activationLink}}, {{unsubscribeUrl}}
• Conditionals: {{#isPremium}}Premium content{{/isPremium}}
• Loops: {{#items}}<li>{{name}}</li>{{/items}}

Template Example

<!DOCTYPE html>
<html>
<head>
    <title>{{subject}}</title>
</head>
<body>
    <h1>Hello {{firstName}}!</h1>

    {{#isWelcome}}
    <p>Welcome to {{companyName}}! We're excited to have you.</p>
    {{/isWelcome}}

    <h2>Your Recent Orders:</h2>
    <ul>
    {{#orders}}
        <li>{{productName}} - ${{price}}</li>
    {{/orders}}
    </ul>

    <p>Best regards,<br>The {{companyName}} Team</p>

    <footer>
        <a href="{{unsubscribeUrl}}">Unsubscribe</a>
    </footer>
</body>
</html>

Bulk Email Operations

Batch Sending

Send emails to multiple recipients efficiently:

curl -X POST https://api.mailiam.dev/email/batch \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "newsletter",
    "recipients": [
      {
        "email": "user1@example.com",
        "variables": {"firstName": "John", "plan": "premium"}
      },
      {
        "email": "user2@example.com",
        "variables": {"firstName": "Jane", "plan": "basic"}
      }
    ]
  }'

Mailing Lists

Create and manage mailing lists:

# Create list
curl -X POST https://api.mailiam.dev/email/lists \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "name": "Newsletter Subscribers",
    "description": "Weekly newsletter recipients"
  }'

# Add subscribers
curl -X POST https://api.mailiam.dev/email/lists/list_123/subscribers \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "subscribers": [
      {"email": "user1@example.com", "name": "John Doe"},
      {"email": "user2@example.com", "name": "Jane Smith"}
    ]
  }'

# Send to list
curl -X POST https://api.mailiam.dev/email/send \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "list": "list_123",
    "subject": "Weekly Newsletter",
    "template": "newsletter"
  }'

Suppression Lists

Manage unsubscribed and bounced addresses:

# Add to suppression list
curl -X POST https://api.mailiam.dev/email/suppression \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "email": "bounced@example.com",
    "reason": "bounced"
  }'

# Check if email is suppressed
curl -H "Authorization: Bearer your-api-key" \
  https://api.mailiam.dev/email/suppression/check?email=user@example.com

Delivery and Analytics

Email Status Tracking

Check email delivery status:

curl -H "Authorization: Bearer your-api-key" \
  https://api.mailiam.dev/email/status/msg_abc123

Response:

{
  "messageId": "msg_abc123",
  "status": "delivered",
  "events": [
    {
      "type": "queued",
      "timestamp": "2024-01-10T10:00:00Z"
    },
    {
      "type": "sent",
      "timestamp": "2024-01-10T10:00:05Z"
    },
    {
      "type": "delivered",
      "timestamp": "2024-01-10T10:00:12Z"
    },
    {
      "type": "opened",
      "timestamp": "2024-01-10T10:15:30Z"
    }
  ]
}

Analytics Dashboard

Get sending statistics:

curl -H "Authorization: Bearer your-api-key" \
  "https://api.mailiam.dev/email/analytics?period=last_30_days"

Response:

{
  "period": "last_30_days",
  "emails_sent": 15420,
  "delivered": 14889,
  "bounced": 234,
  "complaints": 12,
  "opens": 8945,
  "clicks": 2134,
  "unsubscribes": 45,
  "delivery_rate": 96.5,
  "open_rate": 60.1,
  "click_rate": 23.9
}

Webhook Events

Receive real-time delivery events:

curl -X POST https://api.mailiam.dev/email/webhooks \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["delivered", "bounced", "opened", "clicked"]
  }'

Webhook payload example:

{
  "type": "delivered",
  "messageId": "msg_abc123",
  "recipient": "user@example.com",
  "timestamp": "2024-01-10T10:00:12Z",
  "metadata": {
    "campaignId": "newsletter_jan_2024"
  }
}

Integration Examples

Node.js Integration

const mailiam = require('@mailiam/node');

const client = new mailiam.Client({
  apiKey: 'your-api-key'
});

async function sendWelcomeEmail(userEmail, firstName) {
  try {
    const result = await client.email.send({
      to: userEmail,
      template: 'welcome-email',
      variables: {
        firstName: firstName,
        companyName: 'Acme Corp'
      }
    });

    console.log('Email sent:', result.messageId);
    return result;
  } catch (error) {
    console.error('Email failed:', error);
    throw error;
  }
}

Python Integration

import mailiam

client = mailiam.Client(api_key='your-api-key')

def send_order_confirmation(email, order_data):
    try:
        result = client.email.send(
            to=email,
            subject=f"Order #{order_data['id']} Confirmed",
            template='order-confirmation',
            variables=order_data
        )

        print(f"Email sent: {result['messageId']}")
        return result
    except mailiam.mailiamError as e:
        print(f"Email failed: {e}")
        raise

React Hook

import { useState } from 'react';

function usemailiam(apiKey) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const sendEmail = async (emailData) => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch('https://api.mailiam.dev/email/send', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(emailData)
      });

      if (!response.ok) {
        throw new Error('Failed to send email');
      }

      const result = await response.json();
      setLoading(false);
      return result;
    } catch (err) {
      setError(err.message);
      setLoading(false);
      throw err;
    }
  };

  return { sendEmail, loading, error };
}

Best Practices

Email Deliverability

Sender Reputation:

• Use consistent sender addresses
• Implement SPF/DKIM authentication
• Monitor bounce and complaint rates
• Keep suppression lists updated

Content Quality:

• Write clear, relevant subject lines
• Maintain good text-to-image ratios
• Include unsubscribe links
• Avoid spam trigger words

Rate Limits and Quotas

Default Limits:

• 200 emails per second
• 1M emails per day
• 10MB maximum email size
• 25MB maximum attachment size

Optimization:

• Use batch sending for multiple recipients
• Implement exponential backoff for retries
• Cache templates to reduce API calls
• Monitor your sending quotas

Error Handling

try {
  const result = await client.email.send(emailData);
  console.log('Success:', result.messageId);
} catch (error) {
  switch (error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      // Wait and retry
      await sleep(60000);
      return retryEmail(emailData);

    case 'INVALID_RECIPIENT':
      // Remove from mailing list
      await removeFromList(emailData.to);
      break;

    case 'QUOTA_EXCEEDED':
      // Alert administrators
      await alertAdmins('Email quota exceeded');
      break;

    default:
      console.error('Unexpected error:', error);
  }
}

Troubleshooting

Common Issues

Emails not being delivered?

1. Check sender reputation and authentication
2. Verify recipient email addresses
3. Review content for spam triggers
4. Check suppression lists

High bounce rate?

1. Validate email addresses before sending
2. Remove invalid addresses from lists
3. Use double opt-in for subscriptions
4. Monitor feedback loops

Low open rates?

1. Test subject lines for effectiveness
2. Check sender name recognition
3. Optimize send times
4. Segment your audience

Getting Help

• Monitor your sending with our dashboard
• Check our API Reference for detailed documentation
• Contact support at support@mailiam.dev

Security and Compliance

Data Protection

• All emails encrypted in transit (TLS 1.2+)
• API keys use secure authentication
• Personal data automatically purged
• GDPR compliant data handling

Compliance Features

• CAN-SPAM: Automatic unsubscribe handling
• GDPR: Data export and deletion tools
• CCPA: Privacy controls and transparency
• SOC 2: Security and availability standards

Next Steps

• Learn about Forms for contact form integration
• Check out Email Forwarding for inbound email
• Explore our API Reference for complete documentation
• Try our SDKs and libraries for your platform