> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailofly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rest api automation

# REST API automation

Build custom integrations with Mailofly's REST API — sync CRMs, trigger sends from your backend, and automate campaign workflows.

**Base URL:** `https://api.mailofly.com/v1`

***

## Common patterns

### 1. Transactional send on user action

When a user signs up, completes a purchase, or resets a password:

```bash theme={null}
curl -sS -X POST "https://api.mailofly.com/v1/emails" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <welcome@example.com>",
    "to": ["newuser@example.com"],
    "template": {
      "id": "welcome-template-uuid",
      "variables": { "first_name": "Alex" }
    }
  }'
```

### 2. Sync contacts from your database

```bash theme={null}
# Upsert a contact
curl -sS -X POST "https://api.mailofly.com/v1/contacts" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "Alex",
    "custom_fields": { "plan": "pro" }
  }'

# Add to a segment
curl -sS -X POST "https://api.mailofly.com/v1/segments/SEGMENT_ID/contacts" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "CONTACT_UUID" }'
```

### 3. Trigger a campaign send

```bash theme={null}
curl -sS -X POST "https://api.mailofly.com/v1/campaigns/CAMPAIGN_ID/send" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "sendNow": true }'
```

### 4. Monitor delivery

```bash theme={null}
curl -sS "https://api.mailofly.com/v1/mail-logs?status=failed&page_size=20" \
  -H "Authorization: Bearer mf_live_…"
```

***

## Zapier / n8n / Make

No native connector yet — use **HTTP request** steps:

| Step    | Config                                                                           |
| ------- | -------------------------------------------------------------------------------- |
| Method  | POST                                                                             |
| URL     | `https://api.mailofly.com/v1/emails` (single) or `/v1/emails/batch` (JSON array) |
| Headers | `Authorization: Bearer mf_live_…`, `Content-Type: application/json`              |
| Body    | JSON with `from`, `to`, `subject`, `html` (or `template`)                        |

Trigger on: new CRM lead, form submission, Stripe payment, etc.

***

## SDK & code samples

| Language | Approach                                      |
| -------- | --------------------------------------------- |
| Node.js  | `fetch` or `axios` with Bearer header         |
| Python   | `requests.post(url, headers={…}, json={…})`   |
| Ruby     | `Net::HTTP` or `Faraday`                      |
| Go       | `http.NewRequest` with `Authorization` header |

Every endpoint page includes ready-to-run **cURL** — translate directly to your language.

***

## Error handling

```javascript theme={null}
const res = await fetch("https://api.mailofly.com/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILOFLY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

if (!res.ok) {
  const err = await res.json();
  // { error: "…", message: "…" }
  throw new Error(err.message);
}

const { data } = await res.json();
```

Retry **5xx** errors with exponential backoff. Don't retry **4xx** except **429** (rate limit).

***

## Related

* [API overview](https://docs.mailofly.com/api)
* [API keys](https://docs.mailofly.com/getting-started/api-keys)
* [Webhooks](webhooks.md) — push-based mail status events


## Related topics

- [Integrations](/integrations/index.md)
- [Introduction](/api/index.md)
- [Send with API](/broadcasts/send-with-api.md)
- [Index](/changelog/index.md)
- [Create API key](/getting-started/api-keys.md)