Use the Mailsoftly API
Create a Mailsoftly API key, copy it while it is on screen, then use the developer docs to authenticate and make your first REST API call.
When a ready made integration does not cover what you need, the Mailsoftly REST API does. It is the same API our own connectors call: contacts, lists, tags, custom fields, campaign drafts, sending, and global unsubscribes.
Two things get you there. A key you create in Settings, and the developer documentation site that lists every endpoint the key can reach. This guide walks both, then makes one real call end to end.
Create an API key
Open Settings, find the Advanced group in the left sidebar, and click API. Everything to do with keys lives on that one screen. Typing api key into global search takes you there too.
Press Create New API Key at the top right. The modal that opens is titled Generate API Key and asks for two things.
- A name. Make it the name of the thing that will use the key, not something generic. When a key later shows up as unused, or you have to revoke one in a hurry, the name is what tells you what will break.
- How much access it gets. Full access is selected for you, and it lets the key use every part of the API. Choose Limited access instead and a checklist appears with seven permissions: read your contacts, lists and tags; create and update contacts, lists and tags; read your campaigns and their reports; create and edit campaign drafts; send or schedule campaigns to your contacts; add addresses to your suppression list; read your account and company profile.
Tick only what the integration actually does. A form that posts new signups needs the two contact permissions and nothing else, and a key that cannot send campaigns cannot send one by accident. If you leave every box empty, the key is created with full access instead.
Copy the key while it is on screen
Submit the form and Mailsoftly shows you the key once. That is not a figure of speech: only a fingerprint of the key is stored, so nothing in the product can ever print the full value again. The modal will not close if you click outside it or press escape, which is deliberate.
Copy it with the Copy button, put it straight into wherever it is going to live, and only then press Done. If you lose it, there is no recovery step. Revoke the key and create another one.
Underneath the key you will see the date it expires. New keys last one year from the day they are created.
Treat the key like a password, because that is exactly what it is. Anyone holding it can act on your account with whatever access you gave it. Keep it out of email, out of chat, and out of anything you commit to a code repository.
Keep the list of keys honest
Back on the API screen, every key you hold is listed newest first, and each row tells you four useful things: when it was created, when it expires, when it was last used, and how much access it carries. A key that has never been called says so.
You can rename a key in place by clicking its name. You cannot see its value again; the row shows only the first few characters.
Revoke sits at the end of each row, named rather than hidden behind a hover, because revoking is the only real fix for a key that has leaked. It takes effect immediately and anything still using that key starts failing straight away.
Keys created before expiry dates existed read Never expires and keep working. Everything issued since stops a year after it was created, and Mailsoftly warns you twice: a banner appears on this screen 45 days out listing the keys and their dates, and your admins get one email 30 days out. Rotating means creating a new key, pointing the integration at it, and only then revoking the old one.
Everyone on your team can open this screen. Creating a key and revoking one need an Admin, or a teammate whose access to email work is set to write. Reading the whole list with fresh eyes once a quarter is worth the five minutes: Review connected apps and access keys turns it into a routine.
Open the developer documentation
The endpoint reference lives at app.mailsoftly.com/developers. It is a public page, so you can send the link to a developer who has no Mailsoftly login at all, and it opens without signing in. Inside the product, typing api documentation into global search takes you to the same place.
The page has three parts worth knowing.
- An interactive reference, grouped by area: Authentication, Contacts, Contact Lists, Tags, Custom Fields, Emails, Unsubscribes and the rest. Open an endpoint and you get its parameters, an example request, an example response, and ready made code samples.
- A raw machine readable spec at app.mailsoftly.com/developers/openapi.json, linked from the page as Download OpenAPI Spec. That file is what most API clients and code generators want, and it is generated from the running app rather than maintained by hand.
- A second tab, MCP Documentation, for connecting an assistant to your account. That is a separate job with its own guide: Connect an AI assistant with MCP.
One thing to watch as you read: the reference lists endpoints that are built and endpoints that are planned. Anything whose description opens with Coming Soon has no route behind it yet and will not answer. Automations, forms, landing pages and SMS campaigns are all in that group today.
Bookmark that page. It is the only place where the endpoint list is guaranteed to be current.
Open the Mailsoftly developer documentation
Authenticate a request
Every call goes to app.mailsoftly.com/api/v3 and carries your key in an Authorization header. Send the raw token on its own, with no Bearer in front of it. That is the whole authentication story for an API key.
What you get back when something is wrong is worth knowing before you start debugging.
- No Authorization header at all returns 401 with the message Missing Authorization Information.
- A key we do not recognise returns 401 Unauthorized. A key that has passed its expiry date returns 401 Token expired, which is a different message on purpose.
- A limited key calling an endpoint outside its permissions returns 403, and the body names the permission it needed, so you can fix the key rather than guess.
- A missing or invalid field returns 422. Every error body has the same shape: a status of error and a plain description.
There is one rate limit and it is generous: 300 requests every five minutes from the same address. Go past it and you get 429 with a Retry-After header telling you how long to wait.
Apps you authorize through Mailsoftly rather than build yourself use a different credential, sent with a Bearer prefix. You never create one of those by hand on the API keys screen.
Make your first call
Here is a complete, useful sequence: add one person to one of your lists. It needs a key with permission to read and to create contacts, lists and tags.
- Find the list. Send a GET to /api/v3/get_contact_lists. You get back every general list with its id, its name and its contact count. Keep the id of the list you want.
- Look the person up. Send a GET to /api/v3/search_contacts with email set to their address. The match is exact, not partial, so an empty result really does mean the address is new to you.
- Create or update them. Send a POST to /api/v3/create_or_update_contact with a JSON body carrying email, first_name and last_name. Leave contact_id out and a new contact is created. Pass the contact_id your search returned and that contact is updated instead.
- Add them to the list. Send a POST to /api/v3/add_contact_to_contact_list with contact_id and contact_list_id. Adding someone who is already a member returns an informational message rather than an error, so you do not need to check membership first.
The trap in that sequence is step three. create_or_update_contact does not match on email address. Without a contact_id it always creates, and creating an address you already hold fails validation instead of merging. Search first and you will never hit it.
Once one call works, the rest follow the same pattern: same base address, same header, same error shape. Start with contacts, and reach for sending only when the read side is doing what you expect.
Ready to try it in your own account?
Free to start with your Google Workspace or Microsoft 365 account. No credit card required.
